archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-27 14:54:52 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8307409: Refactor usage examples to use @snippet in the java.nio packages

Browse source 
Reviewed-by: alanb, rriggs
This commit is contained in:
Brian Burkhalter 2023-05-12 15:17:22 +00:00
parent e512a20679
commit 9fa8b9a4a6
33 changed files with 433 additions and 386 deletions
Download patch file Download diff file Expand all files Collapse all files

158
src/java.base/share/classes/java/nio/X-Buffer.java.template
View file

@ -149,12 +149,16 @@ import jdk.internal.util.ArraysSupport;
* <i>get</i> and <i>put</i> methods for each type. For 32-bit floating-point
* values, for example, this class defines:
*
* <blockquote><pre>
* float {@link #getFloat()}
* float {@link #getFloat(int) getFloat(int index)}
* ByteBuffer {@link #putFloat(float) putFloat(float f)}
* ByteBuffer {@link #putFloat(int,float) putFloat(int index, float f)}
* </pre></blockquote>
* {@snippet lang=java :
* // @link substring="getFloat()" target="#getFloat" :
* float getFloat()
* // @link substring="getFloat(int index)" target="#getFloat(int)" :
* float getFloat(int index)
* // @link substring="putFloat(float f)" target="#putFloat(float)" :
* ByteBuffer putFloat(float f)
* // @link substring="putFloat(int index, float f)" target="#putFloat(int,float)" :
* ByteBuffer putFloat(int index, float f)
* }
*
* <p> Corresponding methods are defined for the types {@code char,
* short, int, long}, and {@code double}. The index
@ -231,31 +235,35 @@ import jdk.internal.util.ArraysSupport;
*
* The sequence of statements
*
* <blockquote><pre>
* bb.putInt(0xCAFEBABE);
* bb.putShort(3);
* bb.putShort(45);</pre></blockquote>
* {@snippet lang=java :
* bb.putInt(0xCAFEBABE);
* bb.putShort(3);
* bb.putShort(45);
* }
*
* can, for example, be replaced by the single statement
*
* <blockquote><pre>
* bb.putInt(0xCAFEBABE).putShort(3).putShort(45);</pre></blockquote>
* {@snippet lang=java :
* bb.putInt(0xCAFEBABE).putShort(3).putShort(45);
* }
*
#end[byte]
#if[char]
*
* The sequence of statements
*
* <blockquote><pre>
* cb.put("text/");
* cb.put(subtype);
* cb.put("; charset=");
* cb.put(enc);</pre></blockquote>
* {@snippet lang=java :
* cb.put("text/");
* cb.put(subtype);
* cb.put("; charset=");
* cb.put(enc);
* }
*
* can, for example, be replaced by the single statement
*
* <blockquote><pre>
* cb.put("text/").put(subtype).put("; charset=").put(enc);</pre></blockquote>
* {@snippet lang=java :
* cb.put("text/").put(subtype).put("; charset=").put(enc);
* }
*
#end[char]
* <h2> Optional operations </h2>
@ -780,10 +788,10 @@ public abstract sealed class $Type$Buffer
* <code>src.get(dst,&nbsp;off,&nbsp;len)</code> has exactly the same effect as
* the loop
*
* <pre>{@code
* {@snippet lang=java :
* for (int i = off; i < off + len; i++)
* dst[i] = src.get();
* }</pre>
* }
*
* except that it first checks that there are sufficient $type$s in
* this buffer and it is potentially much more efficient.
@ -830,8 +838,9 @@ public abstract sealed class $Type$Buffer
* destination array. An invocation of this method of the form
* {@code src.get(a)} behaves in exactly the same way as the invocation
*
* <pre>
* src.get(a, 0, a.length) </pre>
* {@snippet lang=java :
* src.get(a, 0, a.length)
* }
*
* @param dst
* The destination array
@ -860,10 +869,10 @@ public abstract sealed class $Type$Buffer
* checks the consistency of the supplied parameters and it is potentially
* much more efficient:
*
* <pre>{@code
* {@snippet lang=java :
* for (int i = offset, j = index; i < offset + length; i++, j++)
* dst[i] = src.get(j);
* }</pre>
* }
*
* @param index
* The index in this buffer from which the first $type$ will be
@ -908,8 +917,9 @@ public abstract sealed class $Type$Buffer
* <code>src.get(index,&nbsp;dst)</code> behaves in exactly the same
* way as the invocation:
*
* <pre>
* src.get(index, dst, 0, dst.length) </pre>
* {@snippet lang=java :
* src.get(index, dst, 0, dst.length)
* }
*
* @param index
* The index in this buffer from which the first $type$ will be
@ -984,9 +994,10 @@ public abstract sealed class $Type$Buffer
* <p> In other words, an invocation of this method of the form
* {@code dst.put(src)} has exactly the same effect as the loop
*
* <pre>
* {@snippet lang=java :
* while (src.hasRemaining())
* dst.put(src.get()); </pre>
* dst.put(src.get());
* }
*
* except that it first checks that there is sufficient space in this
* buffer and it is potentially much more efficient. If this buffer and
@ -1046,10 +1057,10 @@ public abstract sealed class $Type$Buffer
* <code>dst.put(index,&nbsp;src,&nbsp;offset,&nbsp;length)</code>
* has exactly the same effect as the loop
*
* <pre>{@code
* for (int i = offset, j = index; i < offset + length; i++, j++)
* dst.put(j, src.get(i));
* }</pre>
* {@snippet lang=java :
* for (int i = offset, j = index; i < offset + length; i++, j++)
* dst.put(j, src.get(i));
* }
*
* except that it first checks the consistency of the supplied parameters
* and it is potentially much more efficient. If this buffer and
@ -1158,10 +1169,10 @@ public abstract sealed class $Type$Buffer
* <code>dst.put(src,&nbsp;off,&nbsp;len)</code> has exactly the same effect as
* the loop
*
* <pre>{@code
* {@snippet lang=java :
* for (int i = off; i < off + len; i++)
* dst.put(src[i]);
* }</pre>
* }
*
* except that it first checks that there is sufficient space in this
* buffer and it is potentially much more efficient.
@ -1212,8 +1223,9 @@ public abstract sealed class $Type$Buffer
* form {@code dst.put(a)} behaves in exactly the same way as the
* invocation
*
* <pre>
* dst.put(a, 0, a.length) </pre>
* {@snippet lang=java :
* dst.put(a, 0, a.length)
* }
*
* @param src
* The source array
@ -1243,10 +1255,10 @@ public abstract sealed class $Type$Buffer
* checks the consistency of the supplied parameters and it is potentially
* much more efficient:
*
* <pre>{@code
* {@snippet lang=java :
* for (int i = offset, j = index; i < offset + length; i++, j++)
* dst.put(j, src[i]);
* }</pre>
* }
*
* @param index
* The index in this buffer at which the first $type$ will be
@ -1294,8 +1306,9 @@ public abstract sealed class $Type$Buffer
* method of the form <code>dst.put(index,&nbsp;src)</code>
* behaves in exactly the same way as the invocation:
*
* <pre>
* dst.put(index, src, 0, src.length); </pre>
* {@snippet lang=java :
* dst.put(index, src, 0, src.length);
* }
*
* @param index
* The index in this buffer at which the first $type$ will be
@ -1378,10 +1391,10 @@ public abstract sealed class $Type$Buffer
* <code>dst.put(src,&nbsp;start,&nbsp;end)</code> has exactly the same effect
* as the loop
*
* <pre>{@code
* {@snippet lang=java :
* for (int i = start; i < end; i++)
* dst.put(src.charAt(i));
* }</pre>
* }
*
* except that it first checks that there is sufficient space in this
* buffer and it is potentially much more efficient.
@ -1429,8 +1442,9 @@ public abstract sealed class $Type$Buffer
* into this buffer. An invocation of this method of the form
* {@code dst.put(s)} behaves in exactly the same way as the invocation
*
* <pre>
* dst.put(s, 0, s.length()) </pre>
* {@snippet lang=java :
* dst.put(s, 0, s.length())
* }
*
* @param src
* The source string
@ -1646,14 +1660,14 @@ public abstract sealed class $Type$Buffer
* write was incomplete. The following loop, for example, copies bytes
* from one channel to another via the buffer {@code buf}:
*
* <blockquote><pre>{@code
* buf.clear(); // Prepare buffer for use
* while (in.read(buf) >= 0 || buf.position != 0) {
* buf.flip();
* out.write(buf);
* buf.compact(); // In case of partial write
* }
* }</pre></blockquote>
* {@snippet lang=java :
* buf.clear(); // Prepare buffer for use
* while (in.read(buf) >= 0 || buf.position != 0) {
* buf.flip();
* out.write(buf);
* buf.compact(); // In case of partial write
* }
* }
*
#end[byte]
*
@ -1978,8 +1992,9 @@ public abstract sealed class $Type$Buffer
* <p> An invocation of this method of the form {@code dst.append(csq)}
* behaves in exactly the same way as the invocation
*
* <pre>
* dst.put(csq.toString()) </pre>
* {@snippet lang=java :
* dst.put(csq.toString())
* }
*
* <p> Depending on the specification of {@code toString} for the
* character sequence {@code csq}, the entire sequence may not be
@ -2019,8 +2034,9 @@ public abstract sealed class $Type$Buffer
* end)} when {@code csq} is not {@code null}, behaves in exactly the
* same way as the invocation
*
* <pre>
* dst.put(csq.subSequence(start, end).toString()) </pre>
* {@snippet lang=java :
* dst.put(csq.subSequence(start, end).toString())
* }
*
* @param csq
* The character sequence from which a subsequence will be
@ -2073,8 +2089,9 @@ public abstract sealed class $Type$Buffer
* <p> An invocation of this method of the form {@code dst.append($x$)}
* behaves in exactly the same way as the invocation
*
* <pre>
* dst.put($x$) </pre>
* {@snippet lang=java :
* dst.put($x$)
* }
*
* @param $x$
* The 16-bit $type$ to append
@ -2173,14 +2190,17 @@ public abstract sealed class $Type$Buffer
* aligned address. Specifically, the index should either be decremented by
* the return value if the latter is not greater than {@code index}, or be
* incremented by the unit size minus the return value. Therefore given
* <blockquote><pre>
* int value = alignmentOffset(index, unitSize)</pre></blockquote>
* {@snippet lang=java :
* int value = alignmentOffset(index, unitSize)
* }
* then the identities
* <blockquote><pre>
* alignmentOffset(index - value, unitSize) == 0, value &le; index</pre></blockquote>
* {@snippet lang=java :
* alignmentOffset(index - value, unitSize) == 0, value <= index
* }
* and
* <blockquote><pre>
* alignmentOffset(index + (unitSize - value), unitSize) == 0</pre></blockquote>
* {@snippet lang=java :
* alignmentOffset(index + (unitSize - value), unitSize) == 0
* }
* must hold.
*
* @apiNote
@ -2239,10 +2259,10 @@ public abstract sealed class $Type$Buffer
* and limit will be zero. If rounding is within bounds the following
* expressions will be true for a new buffer {@code nb} and unit size
* {@code unitSize}:
* <pre>{@code
* nb.alignmentOffset(0, unitSize) == 0
* nb.alignmentOffset(nb.limit(), unitSize) == 0
* }</pre>
* {@snippet lang=java :
* nb.alignmentOffset(0, unitSize) == 0
* nb.alignmentOffset(nb.limit(), unitSize) == 0
* }
*
* <p> Changes to this buffer's content will be visible in the new
* buffer, and vice versa; the two buffers' position, limit, and mark