Is ShortBuffer.capacity the same as it size or length

Can I use capacity to find the actual size or length of a ShortBuffer? From what I have read it returns the number of elements contained in the buffer. But the word "capacity" is so ambiguous. If I put an array of 5 shorts in this buffer, wi开发者_开发知识库ll capacity always return 5?

No. The capacity is the amount of data the buffer effectively can hold at the moment. It doesn't mean that much data has been written.

If you put an array of 5 shorts in a buffer with a larger capacity, that won't change the capacity, but it will change the position. For example:

import java.nio.*;

public class Test {
    public static void main(String[] args) throws Exception {
        ShortBuffer buffer = ShortBuffer.allocate(100);
        short[] data = new short[5];
        buffer.put(data);
        System.out.println(buffer.capacity()); // Prints 100
        System.out.println(buffer.position()); // Prints 5
    }
}

Of course, if you only initialize the buffer with the capacity you need, that will be the same. But you do need to understand the difference between the two. If you imagine that the buffer is an empty sheet of lined paper, the capacity is how many lines are available on the paper in total, whereas the position will effectively show the position of the next blank line to write in.

If I put an array of 5 shorts in this buffer, will capacity always return 5?

I think the real answer is no. The capacity of a buffer is determined by the parameter you provide when you allocate the buffer, not the number of elements that you put into it.

The Buffer javadoc says this:

A buffer is a linear, finite sequence of elements of a specific primitive type. Aside from its content, the essential properties of a buffer are its capacity, limit, and position:

• A buffer's capacity is the number of elements it contains. The capacity of a buffer is never negative and never changes.

• A buffer's limit is the index of the first element that should not be read or written. A buffer's limit is never negative and is never greater than its capacity.

• A buffer's position is the index of the next element to be read or written. A buffer's position is never negative and is never greater than its limit.

While the wording leaves something to be desired, I discern a distinction between the number of elements it can contain (capacity), and the number of elements it currently contains; typically (limit - position) when reading or position when writing.

This is reinforced by the javadocs for the allocate(int) and put(short) methods. The former states that the parameter gives the buffer capacity, and the latter does NOT state that put will update the buffer capacity.

(On the other hand, you could argue that a buffer literally does "contain" capacity elements at all times, but that some of those elements are not "valid" data.)

Yes, capacity returns the maximum number of elements in the buffer. If you initialise it with a capacity of 5, its capacity will always be 5. Of course, that doesn't mean it will necessarily contain 5 elements.

Yes. According to the Buffer (which is a superclass of ShortBuffer) reference:

"A buffer's capacity is the number of elements it contains."