View Javadoc
1   //******************************************************************************
2   //
3   // File:    Signed8BitIntegerBuf.java
4   // Package: edu.rit.mp
5   // Unit:    Class edu.rit.mp.Signed8BitIntegerBuf
6   //
7   // This Java source file is copyright (C) 2007 by Alan Kaminsky. All rights
8   // reserved. For further information, contact the author, Alan Kaminsky, at
9   // ark@cs.rit.edu.
10  //
11  // This Java source file is part of the Parallel Java Library ("PJ"). PJ is free
12  // software; you can redistribute it and/or modify it under the terms of the GNU
13  // General Public License as published by the Free Software Foundation; either
14  // version 3 of the License, or (at your option) any later version.
15  //
16  // PJ is distributed in the hope that it will be useful, but WITHOUT ANY
17  // WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
18  // A PARTICULAR PURPOSE. See the GNU General Public License for more details.
19  //
20  // Linking this library statically or dynamically with other modules is making a
21  // combined work based on this library. Thus, the terms and conditions of the GNU
22  // General Public License cover the whole combination.
23  //
24  // As a special exception, the copyright holders of this library give you
25  // permission to link this library with independent modules to produce an
26  // executable, regardless of the license terms of these independent modules, and
27  // to copy and distribute the resulting executable under terms of your choice,
28  // provided that you also meet, for each linked independent module, the terms
29  // and conditions of the license of that module. An independent module is a module
30  // which is not derived from or based on this library. If you modify this library,
31  // you may extend this exception to your version of the library, but you are not
32  // obligated to do so. If you do not wish to do so, delete this exception
33  // statement from your version.
34  //
35  // A copy of the GNU General Public License is provided in the file gpl.txt. You
36  // may also obtain a copy of the GNU General Public License on the World Wide
37  // Web at http://www.gnu.org/licenses/gpl.html.
38  //
39  //******************************************************************************
40  package edu.rit.mp;
41  
42  import java.nio.ByteBuffer;
43  
44  import edu.rit.mp.buf.EmptySigned8BitIntegerBuf;
45  import edu.rit.mp.buf.SharedSigned8BitIntegerArrayBuf;
46  import edu.rit.mp.buf.SharedSigned8BitIntegerArrayBuf_1;
47  import edu.rit.mp.buf.SharedSigned8BitIntegerBuf;
48  import edu.rit.mp.buf.Signed8BitIntegerArrayBuf;
49  import edu.rit.mp.buf.Signed8BitIntegerArrayBuf_1;
50  import edu.rit.mp.buf.Signed8BitIntegerItemBuf;
51  import edu.rit.mp.buf.Signed8BitIntegerMatrixBuf;
52  import edu.rit.mp.buf.Signed8BitIntegerMatrixBuf_1;
53  import edu.rit.pj.reduction.SharedInteger;
54  import edu.rit.pj.reduction.SharedIntegerArray;
55  import edu.rit.util.Arrays;
56  import edu.rit.util.Range;
57  
58  /**
59   * Class Signed8BitIntegerBuf is the abstract base class for a buffer of signed
60   * 8-bit integer items sent or received using the Message Protocol (MP). In a
61   * message, a signed 8-bit integer item is represented as one byte. The range of
62   * values that can be represented is -128 .. 127.
63   * <P>
64   * A buffer may be used to send one or more messages at the same time in
65   * multiple threads. If a buffer is being used to send a message or messages,
66   * the buffer must not be used to receive a message at the same time.
67   * <P>
68   * A buffer may be used to receive one message at a time. If a buffer is being
69   * used to receive a message, the buffer must not be used to receive another
70   * message in a different thread, and the buffer must not be used to send a
71   * message or messages.
72   * <P>
73   * A buffer is a conduit for retrieving and storing data in some underlying data
74   * structure. If the underlying data structure is multiple thread safe, then one
75   * thread can be retrieving or storing data via the buffer at the same time as
76   * other threads are accessing the data structure. If the underlying data
77   * structure is not multiple thread safe, then other threads must not access the
78   * data structure while one thread is retrieving or storing data via the buffer.
79   * <P>
80   * To create a Signed8BitIntegerBuf, call one of the following static factory
81   * methods:
82   * <UL>
83   * <LI><code>emptyBuffer()</code>
84   * <LI><code>buffer()</code>
85   * <LI><code>buffer (int)</code>
86   * <LI><code>buffer (int[])</code>
87   * <LI><code>sliceBuffer (int[], Range)</code>
88   * <LI><code>sliceBuffers (int[], Range[])</code>
89   * <LI><code>buffer (int[][])</code>
90   * <LI><code>rowSliceBuffer (int[][], Range)</code>
91   * <LI><code>rowSliceBuffers (int[][], Range[])</code>
92   * <LI><code>colSliceBuffer (int[][], Range)</code>
93   * <LI><code>colSliceBuffers (int[][], Range[])</code>
94   * <LI><code>patchBuffer (int[][], Range, Range)</code>
95   * <LI><code>patchBuffers (int[][], Range[], Range[])</code>
96   * <LI><code>buffer (SharedInteger)</code>
97   * <LI><code>buffer (SharedIntegerArray)</code>
98   * <LI><code>sliceBuffer (SharedIntegerArray, Range)</code>
99   * <LI><code>sliceBuffers (SharedIntegerArray, Range[])</code>
100  * </UL>
101  *
102  * @author Alan Kaminsky
103  * @version 03-May-2008
104  */
105 public abstract class Signed8BitIntegerBuf
106         extends Buf {
107 
108 // Hidden constructors.
109     /**
110      * Construct a new signed 8-bit integer buffer.
111      *
112      * @param theLength Number of items.
113      * @exception IllegalArgumentException (unchecked exception) Thrown if
114      * <code>theLength</code> &lt; 0.
115      */
116     protected Signed8BitIntegerBuf(int theLength) {
117         super(Constants.TYPE_SIGNED_8_BIT_INTEGER, theLength);
118     }
119 
120 // Exported operations.
121     /**
122      * Create an empty buffer. The buffer's length is 0. The buffer's item type
123      * is signed 8-bit integer.
124      *
125      * @return Empty buffer.
126      */
127     public static Signed8BitIntegerBuf emptyBuffer() {
128         return new EmptySigned8BitIntegerBuf();
129     }
130 
131     /**
132      * Create a buffer for an integer item. The item is stored in the
133      * <code>item</code> field of the buffer.
134      *
135      * @return Buffer.
136      */
137     public static Signed8BitIntegerItemBuf buffer() {
138         return new Signed8BitIntegerItemBuf();
139     }
140 
141     /**
142      * Create a buffer for an integer item with the given initial value. The
143      * item is stored in the <code>item</code> field of the buffer.
144      *
145      * @param item Initial value of the <code>item</code> field.
146      * @return Buffer.
147      */
148     public static Signed8BitIntegerItemBuf buffer(int item) {
149         return new Signed8BitIntegerItemBuf(item);
150     }
151 
152     /**
153      * Create a buffer for the entire given integer array. The returned buffer
154      * encompasses all the elements in <code>theArray</code>.
155      *
156      * @param theArray Array.
157      * @return Buffer.
158      * @exception NullPointerException (unchecked exception) Thrown if
159      * <code>theArray</code> is null.
160      */
161     public static Signed8BitIntegerBuf buffer(int[] theArray) {
162         if (theArray == null) {
163             throw new NullPointerException("Signed8BitIntegerBuf.buffer(): theArray is null");
164         }
165         int nr = Arrays.length(theArray);
166         return new Signed8BitIntegerArrayBuf_1(theArray, new Range(0, nr - 1));
167     }
168 
169     /**
170      * Create a buffer for one slice of the given integer array. The returned
171      * buffer encompasses <code>theRange</code> of elements in <code>theArray</code>.
172      * The range's stride may be 1 or greater than 1.
173      *
174      * @param theArray Array.
175      * @param theRange Range of elements to include.
176      * @return Buffer.
177      * @exception NullPointerException (unchecked exception) Thrown if
178      * <code>theArray</code> is null or
179      * <code>theRange</code> is null.
180      * @exception IndexOutOfBoundsException (unchecked exception) Thrown if
181      * <code>theArray</code> does not include all the indexes in <code>theRange</code>.
182      */
183     public static Signed8BitIntegerBuf sliceBuffer(int[] theArray,
184             Range theRange) {
185         if (theArray == null) {
186             throw new NullPointerException("Signed8BitIntegerBuf.sliceBuffer(): theArray is null");
187         }
188         int nr = Arrays.length(theArray);
189         if (0 > theRange.lb() || theRange.ub() >= nr) {
190             throw new IndexOutOfBoundsException("Signed8BitIntegerBuf.sliceBuffer(): theArray index range = 0.."
191                     + (nr - 1) + ", theRange = " + theRange);
192         }
193         if (theRange.stride() == 1) {
194             return new Signed8BitIntegerArrayBuf_1(theArray, theRange);
195         } else {
196             return new Signed8BitIntegerArrayBuf(theArray, theRange);
197         }
198     }
199 
200     /**
201      * Create an array of buffers for multiple slices of the given integer
202      * array. The returned buffer array has the same length as
203      * <code>theRanges</code>. Each element [<I>i</I>] of the returned buffer array
204      * encompasses the elements of <code>theArray</code> specified by
205      * <code>theRanges[i]</code>. Each range's stride may be 1 or greater than 1.
206      *
207      * @param theArray Array.
208      * @param theRanges Array of ranges of elements to include.
209      * @return Array of buffers.
210      * @exception NullPointerException (unchecked exception) Thrown if
211      * <code>theArray</code> is null or
212      * <code>theRanges</code> or any element thereof is null.
213      * @exception IndexOutOfBoundsException (unchecked exception) Thrown if
214      * <code>theArray</code>'s allocation does not include any element of
215      * <code>theRanges</code>.
216      */
217     public static Signed8BitIntegerBuf[] sliceBuffers(int[] theArray,
218             Range[] theRanges) {
219         int n = theRanges.length;
220         Signed8BitIntegerBuf[] result = new Signed8BitIntegerBuf[n];
221         for (int i = 0; i < n; ++i) {
222             result[i] = sliceBuffer(theArray, theRanges[i]);
223         }
224         return result;
225     }
226 
227     /**
228      * Create a buffer for the entire given integer matrix. The returned buffer
229      * encompasses all the rows and all the columns in
230      * <code>theMatrix</code>.
231      *
232      * @param theMatrix Matrix.
233      * @return Buffer.
234      * @exception NullPointerException (unchecked exception) Thrown if
235      * <code>theMatrix</code> is null.
236      */
237     public static Signed8BitIntegerBuf buffer(int[][] theMatrix) {
238         if (theMatrix == null) {
239             throw new NullPointerException("Signed8BitIntegerBuf.buffer(): theMatrix is null");
240         }
241         int nr = Arrays.rowLength(theMatrix);
242         int nc = Arrays.colLength(theMatrix, 0);
243         return new Signed8BitIntegerMatrixBuf_1(theMatrix, new Range(0, nr - 1), new Range(0, nc - 1));
244     }
245 
246     /**
247      * Create a buffer for one row slice of the given integer matrix. The
248      * returned buffer encompasses <code>theRowRange</code> of rows, and all the
249      * columns, in <code>theMatrix</code>. The range's stride may be 1 or greater
250      * than 1.
251      *
252      * @param theMatrix Matrix.
253      * @param theRowRange Range of rows to include.
254      * @return Buffer.
255      * @exception NullPointerException (unchecked exception) Thrown if
256      * <code>theMatrix</code> is null or
257      * <code>theRowRange</code> is null.
258      * @exception IndexOutOfBoundsException (unchecked exception) Thrown if
259      * <code>theMatrix</code>'s allocation does not include <code>theRowRange</code>.
260      */
261     public static Signed8BitIntegerBuf rowSliceBuffer(int[][] theMatrix,
262             Range theRowRange) {
263         if (theMatrix == null) {
264             throw new NullPointerException("Signed8BitIntegerBuf.rowSliceBuffer(): theMatrix is null");
265         }
266         int nr = Arrays.rowLength(theMatrix);
267         if (0 > theRowRange.lb() || theRowRange.ub() >= nr) {
268             throw new IndexOutOfBoundsException("Signed8BitIntegerBuf.rowSliceBuffer(): theMatrix row index range = 0.."
269                     + (nr - 1) + ", theRowRange = " + theRowRange);
270         }
271         int nc = Arrays.colLength(theMatrix, theRowRange.lb());
272         if (theRowRange.stride() == 1) {
273             return new Signed8BitIntegerMatrixBuf_1(theMatrix, theRowRange, new Range(0, nc - 1));
274         } else {
275             return new Signed8BitIntegerMatrixBuf(theMatrix, theRowRange, new Range(0, nc - 1));
276         }
277     }
278 
279     /**
280      * Create an array of buffers for multiple row slices of the given integer
281      * matrix. The returned buffer array has the same length as
282      * <code>theRowRanges</code>. Each element [<I>i</I>] of the returned buffer
283      * array encompasses the rows of <code>theMatrix</code> specified by
284      * <code>theRowRanges[i]</code> and all the columns of <code>theMatrix</code>. Each
285      * range's stride may be 1 or greater than 1.
286      *
287      * @param theMatrix Matrix.
288      * @param theRowRanges Array of ranges of rows to include.
289      * @return Array of buffers.
290      * @exception NullPointerException (unchecked exception) Thrown if
291      * <code>theMatrix</code> is null or
292      * <code>theRowRanges</code> or any element thereof is null.
293      * @exception IndexOutOfBoundsException (unchecked exception) Thrown if
294      * <code>theMatrix</code>'s allocation does not include any element of
295      * <code>theRowRanges</code>.
296      */
297     public static Signed8BitIntegerBuf[] rowSliceBuffers(int[][] theMatrix,
298             Range[] theRowRanges) {
299         int n = theRowRanges.length;
300         Signed8BitIntegerBuf[] result = new Signed8BitIntegerBuf[n];
301         for (int i = 0; i < n; ++i) {
302             result[i] = rowSliceBuffer(theMatrix, theRowRanges[i]);
303         }
304         return result;
305     }
306 
307     /**
308      * Create a buffer for one column slice of the given integer matrix. The
309      * returned buffer encompasses all the rows, and <code>theColRange</code> of
310      * columns, in <code>theMatrix</code>. The range's stride may be 1 or greater
311      * than 1.
312      *
313      * @param theMatrix Matrix.
314      * @param theColRange Range of columns to include.
315      * @return Buffer.
316      * @exception NullPointerException (unchecked exception) Thrown if
317      * <code>theMatrix</code> is null or
318      * <code>theColRange</code> is null.
319      * @exception IndexOutOfBoundsException (unchecked exception) Thrown if
320      * <code>theMatrix</code>'s allocation does not include <code>theColRange</code>.
321      */
322     public static Signed8BitIntegerBuf colSliceBuffer(int[][] theMatrix,
323             Range theColRange) {
324         if (theMatrix == null) {
325             throw new NullPointerException("Signed8BitIntegerBuf.colSliceBuffer(): theMatrix is null");
326         }
327         int nr = Arrays.rowLength(theMatrix);
328         int nc = Arrays.colLength(theMatrix, 0);
329         if (0 > theColRange.lb() || theColRange.ub() >= nc) {
330             throw new IndexOutOfBoundsException("Signed8BitIntegerBuf.colSliceBuffer(): theMatrix column index range = 0.."
331                     + (nc - 1) + ", theColRange = " + theColRange);
332         }
333         if (theColRange.stride() == 1) {
334             return new Signed8BitIntegerMatrixBuf_1(theMatrix, new Range(0, nr - 1), theColRange);
335         } else {
336             return new Signed8BitIntegerMatrixBuf(theMatrix, new Range(0, nr - 1), theColRange);
337         }
338     }
339 
340     /**
341      * Create an array of buffers for multiple column slices of the given
342      * integer matrix. The returned buffer array has the same length as
343      * <code>theColRanges</code>. Each element [<I>i</I>] of the returned buffer
344      * array encompasses all the rows of <code>theMatrix</code> and the columns of
345      * <code>theMatrix</code> specified by <code>theColRanges[i]</code>. Each range's
346      * stride may be 1 or greater than 1.
347      *
348      * @param theMatrix Matrix.
349      * @param theColRanges Array of ranges of columns to include.
350      * @return Array of buffers.
351      * @exception NullPointerException (unchecked exception) Thrown if
352      * <code>theMatrix</code> is null or
353      * <code>theColRanges</code> or any element thereof is null.
354      * @exception IndexOutOfBoundsException (unchecked exception) Thrown if
355      * <code>theMatrix</code>'s allocation does not include any element of
356      * <code>theColRanges</code>.
357      */
358     public static Signed8BitIntegerBuf[] colSliceBuffers(int[][] theMatrix,
359             Range[] theColRanges) {
360         int n = theColRanges.length;
361         Signed8BitIntegerBuf[] result = new Signed8BitIntegerBuf[n];
362         for (int i = 0; i < n; ++i) {
363             result[i] = colSliceBuffer(theMatrix, theColRanges[i]);
364         }
365         return result;
366     }
367 
368     /**
369      * Create a buffer for one patch of the given integer matrix. The returned
370      * buffer encompasses <code>theRowRange</code> of rows, and <code>theColRange</code>
371      * of columns, in <code>theMatrix</code>. Each range's stride may be 1 or
372      * greater than 1.
373      *
374      * @param theMatrix Matrix.
375      * @param theRowRange Range of rows to include.
376      * @param theColRange Range of columns to include.
377      * @return Buffer.
378      * @exception NullPointerException (unchecked exception) Thrown if
379      * <code>theMatrix</code> is null,
380      * <code>theRowRange</code> is null, or <code>theColRange</code> is null.
381      * @exception IndexOutOfBoundsException (unchecked exception) Thrown if
382      * <code>theMatrix</code>'s allocation does not include <code>theRowRange</code> and
383      * <code>theColRange</code>.
384      */
385     public static Signed8BitIntegerBuf patchBuffer(int[][] theMatrix,
386             Range theRowRange,
387             Range theColRange) {
388         if (theMatrix == null) {
389             throw new NullPointerException("Signed8BitIntegerBuf.patchBuffer(): theMatrix is null");
390         }
391         int nr = Arrays.rowLength(theMatrix);
392         if (0 > theRowRange.lb() || theRowRange.ub() >= nr) {
393             throw new IndexOutOfBoundsException("Signed8BitIntegerBuf.patchBuffer(): theMatrix row index range = 0.."
394                     + (nr - 1) + ", theRowRange = " + theRowRange);
395         }
396         int nc = Arrays.colLength(theMatrix, theRowRange.lb());
397         if (0 > theColRange.lb() || theColRange.ub() >= nc) {
398             throw new IndexOutOfBoundsException("Signed8BitIntegerBuf.patchBuffer(): theMatrix column index range = 0.."
399                     + (nc - 1) + ", theColRange = " + theColRange);
400         }
401         if (theRowRange.stride() == 1 && theColRange.stride() == 1) {
402             return new Signed8BitIntegerMatrixBuf_1(theMatrix, theRowRange, theColRange);
403         } else {
404             return new Signed8BitIntegerMatrixBuf(theMatrix, theRowRange, theColRange);
405         }
406     }
407 
408     /**
409      * Create an array of buffers for multiple patches of the given integer
410      * matrix. The length of the returned buffer array is equal to the length of
411      * <code>theRowRanges</code> times the length of <code>theColRanges</code>. Each
412      * element of the returned buffer array encompasses the rows given in one
413      * element of <code>theRowRanges</code> array, and the columns given in one
414      * element of <code>theColRanges</code> array, in all possible combinations, of
415      * <code>theMatrix</code>. Each range's stride may be 1 or greater than 1.
416      *
417      * @param theMatrix Matrix.
418      * @param theRowRanges Array of ranges of rows to include.
419      * @param theColRanges Array of ranges of columns to include.
420      * @return Array of buffers.
421      * @exception NullPointerException (unchecked exception) Thrown if
422      * <code>theMatrix</code> is null,
423      * <code>theRowRanges</code> or any element thereof is null, or
424      * <code>theColRanges</code> or any element thereof is null.
425      * @exception IndexOutOfBoundsException (unchecked exception) Thrown if
426      * <code>theMatrix</code>'s allocation does not include any element of
427      * <code>theRowRanges</code> or
428      * <code>theColRanges</code>.
429      */
430     public static Signed8BitIntegerBuf[] patchBuffers(int[][] theMatrix,
431             Range[] theRowRanges,
432             Range[] theColRanges) {
433         int m = theRowRanges.length;
434         int n = theColRanges.length;
435         Signed8BitIntegerBuf[] result = new Signed8BitIntegerBuf[m * n];
436         int k = 0;
437         for (int i = 0; i < m; ++i) {
438             Range rowrange = theRowRanges[i];
439             for (int j = 0; j < n; ++j) {
440                 result[k++]
441                         = patchBuffer(theMatrix, rowrange, theColRanges[j]);
442             }
443         }
444         return result;
445     }
446 
447     /**
448      * Create a buffer for a shared integer item. The item is wrapped in an
449      * instance of class {@linkplain edu.rit.pj.reduction.SharedInteger
450      * SharedInteger}. Use the methods of the SharedInteger object to access the
451      * actual item.
452      *
453      * @param item SharedInteger object that wraps the item.
454      * @exception NullPointerException (unchecked exception) Thrown if
455      * <code>item</code> is null.
456      * @return a {@link edu.rit.mp.Signed8BitIntegerBuf} object.
457      */
458     public static Signed8BitIntegerBuf buffer(SharedInteger item) {
459         if (item == null) {
460             throw new NullPointerException("Signed8BitIntegerBuf.buffer(): item is null");
461         }
462         return new SharedSigned8BitIntegerBuf(item);
463     }
464 
465     /**
466      * Create a buffer for the entire given shared integer array. The returned
467      * buffer encompasses all the elements in <code>theArray</code>.
468      *
469      * @param theArray Array.
470      * @return Buffer.
471      * @exception NullPointerException (unchecked exception) Thrown if
472      * <code>theArray</code> is null.
473      */
474     public static Signed8BitIntegerBuf buffer(SharedIntegerArray theArray) {
475         if (theArray == null) {
476             throw new NullPointerException("Signed8BitIntegerBuf.buffer(): theArray is null");
477         }
478         int nr = theArray.length();
479         return new SharedSigned8BitIntegerArrayBuf_1(theArray, new Range(0, nr - 1));
480     }
481 
482     /**
483      * Create a buffer for one slice of the given shared integer array. The
484      * returned buffer encompasses <code>theRange</code> of elements in
485      * <code>theArray</code>. The range's stride may be 1 or greater than 1.
486      *
487      * @param theArray Array.
488      * @param theRange Range of elements to include.
489      * @return Buffer.
490      * @exception NullPointerException (unchecked exception) Thrown if
491      * <code>theArray</code> is null or
492      * <code>theRange</code> is null.
493      * @exception IndexOutOfBoundsException (unchecked exception) Thrown if
494      * <code>theArray</code> does not include all the indexes in <code>theRange</code>.
495      */
496     public static Signed8BitIntegerBuf sliceBuffer(SharedIntegerArray theArray,
497             Range theRange) {
498         if (theArray == null) {
499             throw new NullPointerException("Signed8BitIntegerBuf.sliceBuffer(): theArray is null");
500         }
501         int nr = theArray.length();
502         if (0 > theRange.lb() || theRange.ub() >= nr) {
503             throw new IndexOutOfBoundsException("Signed8BitIntegerBuf.sliceBuffer(): theArray index range = 0.."
504                     + (nr - 1) + ", theRange = " + theRange);
505         }
506         if (theRange.stride() == 1) {
507             return new SharedSigned8BitIntegerArrayBuf_1(theArray, theRange);
508         } else {
509             return new SharedSigned8BitIntegerArrayBuf(theArray, theRange);
510         }
511     }
512 
513     /**
514      * Create an array of buffers for multiple slices of the given shared
515      * integer array. The returned buffer array has the same length as
516      * <code>theRanges</code>. Each element [<I>i</I>] of the returned buffer array
517      * encompasses the elements of <code>theArray</code> specified by
518      * <code>theRanges[i]</code>. Each range's stride may be 1 or greater than 1.
519      *
520      * @param theArray Array.
521      * @param theRanges Array of ranges of elements to include.
522      * @return Array of buffers.
523      * @exception NullPointerException (unchecked exception) Thrown if
524      * <code>theArray</code> is null or
525      * <code>theRanges</code> or any element thereof is null.
526      * @exception IndexOutOfBoundsException (unchecked exception) Thrown if
527      * <code>theArray</code>'s allocation does not include any element of
528      * <code>theRanges</code>.
529      */
530     public static Signed8BitIntegerBuf[] sliceBuffers(SharedIntegerArray theArray,
531             Range[] theRanges) {
532         int n = theRanges.length;
533         Signed8BitIntegerBuf[] result = new Signed8BitIntegerBuf[n];
534         for (int i = 0; i < n; ++i) {
535             result[i] = sliceBuffer(theArray, theRanges[i]);
536         }
537         return result;
538     }
539 
540     /**
541      * Obtain the given item from this buffer.
542      * <P>
543      * The <code>get()</code> method must not block the calling thread; if it does,
544      * all message I/O in MP will be blocked.
545      *
546      * @param i Item index in the range 0 .. <code>length()</code>-1.
547      * @return Item at index <code>i</code>.
548      */
549     public abstract int get(int i);
550 
551     /**
552      * Store the given item in this buffer.
553      * <P>
554      * The <code>put()</code> method must not block the calling thread; if it does,
555      * all message I/O in MP will be blocked.
556      *
557      * @param i Item index in the range 0 .. <code>length()</code>-1.
558      * @param item Item to be stored at index <code>i</code>.
559      */
560     public abstract void put(int i,
561             int item);
562 
563     /**
564      * {@inheritDoc}
565      *
566      * Copy items from the given buffer to this buffer. The number of items
567      * copied is this buffer's length or <code>theSrc</code>'s length, whichever is
568      * smaller. If <code>theSrc</code> is this buffer, the <code>copy()</code> method
569      * does nothing.
570      * <P>
571      * The default implementation of the <code>copy()</code> method calls the
572      * <code>defaultCopy()</code> method. A subclass can override the
573      * <code>copy()</code> method to use a more efficient algorithm.
574      * @exception ClassCastException (unchecked exception) Thrown if
575      * <code>theSrc</code>'s item data type is not the same as this buffer's item
576      * data type.
577      */
578     public void copy(Buf theSrc) {
579         if (theSrc != this) {
580             defaultCopy((Signed8BitIntegerBuf) theSrc, this);
581         }
582     }
583 
584     /**
585      * {@inheritDoc}
586      *
587      * Fill this buffer with the given item. The <code>item</code> is assigned to
588      * each element in this buffer.
589      * <P>
590      * The <code>item</code> must be an instance of class Integer. If the
591      * <code>item</code> is null, 0 is assigned to each element in this buffer.
592      * @exception ClassCastException (unchecked exception) Thrown if the
593      * <code>item</code>'s data type is not the same as this buffer's item data
594      * type.
595      */
596     public void fill(Object item) {
597         int value = item == null ? 0 : ((Integer) item).intValue();
598         for (int i = 0; i < myLength; ++i) {
599             put(i, value);
600         }
601     }
602 
603     /**
604      * Create a temporary buffer with the same type of items and the same length
605      * as this buffer. The new buffer items are stored in a newly created array,
606      * separate from the storage for this buffer's items.
607      *
608      * @return a {@link edu.rit.mp.Buf} object.
609      */
610     public Buf getTemporaryBuf() {
611         return buffer(new int[myLength]);
612     }
613 
614 // Hidden operations.
615     /**
616      * Skip as many items as possible from the given byte buffer.
617      *
618      * @param num Number of items to skip.
619      * @param buffer Buffer.
620      *
621      * @return Number of items actually skipped.
622      */
623     int skipItems(int num,
624             ByteBuffer buffer) {
625         int n = Math.min(num, buffer.remaining());
626         buffer.position(buffer.position() + n);
627         return n;
628     }
629 
630     /**
631      * Copy items from the given source buffer to the given destination buffer.
632      * The number of items copied is <code>theSrc</code>'s length or
633      * <code>theDst</code>'s length, whichever is smaller. Each item is copied
634      * individually using the <code>get()</code> and <code>put()</code> methods. It is
635      * assumed that <code>theSrc</code> is not the same as <code>theDst</code>.
636      *
637      * @param theSrc Source of items to copy.
638      * @param theDst Destination of items to copy.
639      */
640     protected static void defaultCopy(Signed8BitIntegerBuf theSrc,
641             Signed8BitIntegerBuf theDst) {
642         int n = Math.min(theSrc.myLength, theDst.myLength);
643         for (int i = 0; i < n; ++i) {
644             theDst.put(i, theSrc.get(i));
645         }
646     }
647 
648 }