[Jython-checkins] jython: PyByteArray and BaseBytes Javadoc improvements
jeff.allen
jython-checkins at python.org
Tue Feb 12 16:29:17 CET 2013
http://hg.python.org/jython/rev/7d8005de6b19
changeset: 7045:7d8005de6b19
parent: 7034:6b4a1088566e
user: Jeff Allen <ja...py at farowl.co.uk>
date: Mon Feb 11 17:30:30 2013 +0000
summary:
PyByteArray and BaseBytes Javadoc improvements
Extensive documentation change, and some incidental code changes
of no consequence. (Override tags and whitespace.)
files:
src/org/python/core/BaseBytes.java | 402 +++++++++-----
src/org/python/core/PyByteArray.java | 401 +++++++-------
2 files changed, 459 insertions(+), 344 deletions(-)
diff --git a/src/org/python/core/BaseBytes.java b/src/org/python/core/BaseBytes.java
--- a/src/org/python/core/BaseBytes.java
+++ b/src/org/python/core/BaseBytes.java
@@ -9,12 +9,12 @@
import java.util.ListIterator;
/**
- * Base class for Jython bytearray (and bytes in due course) that provides most of the Java API,
- * including Java List behaviour. Attempts to modify the contents through this API will throw a
- * TypeError if the actual type of the object is not mutable.
- * <p>
- * It is possible for a Java client to treat this class as a <tt>List<PyInteger></tt>, obtaining
- * equivalent functionality to the Python interface in a Java paradigm.
+ * Base class for Jython <code>bytearray</code> (and <code>bytes</code> in due course) that provides
+ * most of the Java API, including Java {@link List} behaviour. Attempts to modify the contents
+ * through this API will throw a <code>TypeError</code> if the actual type of the object is not
+ * mutable. It is possible for a Java client to treat this class as a
+ * <code>List<PyInteger></code>, obtaining equivalent functionality to the Python interface in a
+ * Java paradigm.
* <p>
* Subclasses must define (from {@link PySequence}):
* <ul>
@@ -29,11 +29,29 @@
* <li>{@link #delRange(int, int)}</li>
* </ul>
* since the default implementations will otherwise throw an exception.
+ * <p>
+ * Many of the methods implemented here are inherited or thinly wrapped by {@link PyByteArray},
+ * which offers them as Java API, or exposes them as Python methods. These prototype Python methods
+ * mostly accept a {@link PyObject} as argument, where you might have expected a <code>byte[]</code>
+ * or <code>BaseBytes</code>, in order to accommodate the full range of types accepted by the Python
+ * equivalent: usually, any <code>PyObject</code> that implements {@link BufferProtocol}, providing
+ * a one-dimensional array of bytes, is an acceptable argument. In the documentation, the reader
+ * will often see the terms "byte array" or "object viewable as bytes" instead of
+ * <code>BaseBytes</code> when this broader scope is intended.
+ * <p>
+ * Where the methods return a <code>BaseBytes</code>, this is will normally be an instance of the
+ * class of the object on which the method was actually called. For example {@link #capitalize()},
+ * defined in <code>BaseBytes</code> to return a BaseBytes, actually returns a {@link PyByteArray}
+ * when applied to a <code>bytearray</code>. Or it may be that the method returns a
+ * <code>PyList</code> of instances of the target type, for example {@link #rpartition(PyObject)}.
+ * This is achieved by the sub-class defining {@link #getslice(int, int, int)} and
+ * {@link #getBuilder(int)} to return instances of its own type. See the documentation of particular
+ * methods for more information.
*/
public abstract class BaseBytes extends PySequence implements List<PyInteger> {
/**
- * Simple constructor of empty zero-length array of defined type.
+ * Constructs a zero-length <code>BaseBytes</code> of explicitly-specified sub-type.
*
* @param type explicit Jython type
*/
@@ -44,7 +62,7 @@
}
/**
- * Simple constructor of zero-filled array of defined size and type.
+ * Constructs a zero-filled array of defined size and type.
*
* @param size required
* @param type explicit Jython type
@@ -56,7 +74,7 @@
}
/**
- * Construct byte array of defined type by copying values from int[].
+ * Constructs a byte array of defined type by copying values from int[].
*
* @param type explicit Jython type
* @param value source of values (and size)
@@ -72,8 +90,8 @@
}
/**
- * Construct byte array of defined type by copying character values from a String. These values
- * have to be in the Python byte range 0 to 255.
+ * Constructs a byte array of defined type by copying character values from a String. These
+ * values have to be in the Python byte range 0 to 255.
*
* @param type explicit Jython type
* @param value source of characters
@@ -250,7 +268,8 @@
* @param encoding name of optional encoding
* @param errors name of optional errors policy
* @return encoded string
- * @throws PyException(TypeError) if the PyString is actually a PyUnicode and encoding is null
+ * @throws PyException (TypeError) if the <code>PyString</code> is actually a {@link PyUnicode}
+ * and encoding is <code>null</code>
*/
protected static String encode(PyString arg, String encoding, String errors) throws PyException {
// Jython encode emits a String (not byte[])
@@ -278,7 +297,7 @@
*
* @param start index in this byte array at which the first character code lands
* @param value source of characters
- * @throws PyException(ValueError) if any value[i] > 255
+ * @throws PyException (ValueError) if any value[i] > 255
*/
protected void setBytes(int start, String value) throws PyException {
int n = value.length();
@@ -294,7 +313,7 @@
*
* @param start index in this byte array at which the first character code lands
* @param value source of characters
- * @throws PyException(ValueError) if any value[i] > 255
+ * @throws PyException (ValueError) if any value[i] > 255
*/
protected void setBytes(int start, int step, String value) throws PyException {
int n = value.length();
@@ -307,7 +326,7 @@
/**
* Helper for <code>__new__</code> and <code>__init__</code> and the Java API constructor from
- * int in subclasses. Construct zero-filled bytearray of specified size.
+ * int in subclasses. Construct zero-filled byte array of specified size.
*
* @param n size of zero-filled array
*/
@@ -332,24 +351,11 @@
view.copyTo(storage, offset);
}
-// /**
-// * Helper for the Java API constructor from a {@link #PyBuffer}. View is (perhaps) a stop-gap
-// until
-// * the Jython implementation of PEP 3118 (buffer API) is embedded.
-// *
-// * @param value a byte-oriented view
-// */
-// void init(PyBuffer value) {
-// int n = value.getLen();
-// newStorage(n);
-// value.copyTo(storage, offset);
-// }
-//
/**
* Helper for <code>__new__</code> and <code>__init__</code> and the Java API constructor from
- * bytearray or bytes in subclasses.
+ * <code>bytearray</code> or <code>bytes</code> in subclasses.
*
- * @param source bytearray (or bytes) to copy
+ * @param source <code>bytearray</code> (or <code>bytes</code>) to copy
*/
protected void init(BaseBytes source) {
newStorage(source.size);
@@ -429,8 +435,8 @@
* Load bytes into the container from the given iterable
*
* @param iter iterable source of values to enter into the container
- * @throws PyException(TypeError) if any value not acceptable type
- * @throws PyException(ValueError) if any value<0 or value>255 or string length!=1
+ * @throws PyException (TypeError) if any value not acceptable type
+ * @throws PyException (ValueError) if any value<0 or value>255 or string length!=1
*/
void loadFrom(Iterable<? extends PyObject> iter) throws PyException {
@@ -535,7 +541,7 @@
* Check that an index is within the range of the array, that is <tt>0<=index<size</tt>.
*
* @param index to check
- * @throws PyException(IndexError) if the index is outside the array bounds
+ * @throws PyException (IndexError) if the index is outside the array bounds
*/
protected final void indexCheck(int index) throws PyException {
if (index < 0 || index >= size) {
@@ -569,7 +575,7 @@
* 0..255.)
*
* @param value to convert.
- * @throws PyException(ValueError) if value<0 or value>255
+ * @throws PyException (ValueError) if value<0 or value>255
*/
protected static final byte byteCheck(int value) throws PyException {
if (value < 0 || value > 255) {
@@ -584,7 +590,7 @@
* Python bytes run 0..255.)
*
* @param value to convert.
- * @throws PyException(ValueError) if value<0 or value>255
+ * @throws PyException (ValueError) if value<0 or value>255
*/
protected static final byte byteCheck(PyInteger value) throws PyException {
return byteCheck(value.asInt());
@@ -602,8 +608,8 @@
* </ul>
*
* @param value to convert.
- * @throws PyException(TypeError) if not acceptable type
- * @throws PyException(ValueError) if value<0 or value>255 or string length!=1
+ * @throws PyException (TypeError) if not acceptable type
+ * @throws PyException (ValueError) if value<0 or value>255 or string length!=1
*/
protected static final byte byteCheck(PyObject value) throws PyException {
if (value.isIndex()) {
@@ -627,7 +633,7 @@
* if the return value is not <code>null</code>.
*
* @param b object to wrap
- * @return byte-oriented view or null
+ * @return byte-oriented view or <code>null</code>
*/
protected static PyBuffer getView(PyObject b) {
@@ -673,6 +679,7 @@
* API for org.python.core.PySequence
* ============================================================================================
*/
+ @Override
protected PyInteger pyget(int index) {
return new PyInteger(intAt(index));
}
@@ -681,8 +688,10 @@
* We're not implementing these here, but we can give a stronger guarantee about the return type
* and save some casting and type anxiety.
*/
+ @Override
protected abstract BaseBytes getslice(int start, int stop, int step);
+ @Override
protected abstract BaseBytes repeat(int count);
/*
@@ -696,9 +705,9 @@
*
* @param index to insert at
* @param element to insert (by value)
- * @throws PyException(IndexError) if the index is outside the array bounds
- * @throws PyException(ValueError) if element<0 or element>255
- * @throws PyException(TypeError) if the subclass is immutable
+ * @throws PyException (IndexError) if the index is outside the array bounds
+ * @throws PyException (ValueError) if element<0 or element>255
+ * @throws PyException (TypeError) if the subclass is immutable
*/
public void pyinsert(int index, PyObject element) {
// This won't succeed: it just produces the right error.
@@ -720,8 +729,8 @@
}
/**
- * Class defining the behaviour of bytearray with respect to slice assignment, etc., which
- * differs from the default (list) behaviour in small ways.
+ * Class defining the behaviour of <code>bytearray</code> with respect to slice assignment,
+ * etc., which differs from the default (list) behaviour in small ways.
*/
private class IndexDelegate extends PySequence.DefaultIndexDelegate {
@@ -886,11 +895,11 @@
}
/**
- * Implementation of __eq__ (equality) operator, capable of comparison with another byte array
- * or bytes. Comparison with an invalid type returns null.
+ * Implementation of __eq__ (equality) operator, capable of comparison with another byte array.
+ * Comparison with an invalid type returns <code>null</code>.
*
* @param other Python object to compare with
- * @return Python boolean result or null if not implemented for the other type.
+ * @return Python boolean result or <code>null</code> if not implemented for the other type.
*/
final PyObject basebytes___eq__(PyObject other) {
int cmp = basebytes_cmpeq(other);
@@ -904,11 +913,11 @@
}
/**
- * Implementation of __ne__ (not equals) operator, capable of comparison with another byte array
- * or bytes. Comparison with an invalid type returns null.
+ * Implementation of __ne__ (not equals) operator, capable of comparison with another byte
+ * array. Comparison with an invalid type returns <code>null</code>.
*
* @param other Python object to compare with
- * @return Python boolean result or null if not implemented for the other type.
+ * @return Python boolean result or <code>null</code> if not implemented for the other type.
*/
final PyObject basebytes___ne__(PyObject other) {
int cmp = basebytes_cmpeq(other);
@@ -922,11 +931,11 @@
}
/**
- * Implementation of __lt__ (less than) operator, capable of comparison with another byte array
- * or bytes. Comparison with an invalid type returns null.
+ * Implementation of __lt__ (less than) operator, capable of comparison with another byte array.
+ * Comparison with an invalid type returns <code>null</code>.
*
* @param other Python object to compare with
- * @return Python boolean result or null if not implemented for the other type.
+ * @return Python boolean result or <code>null</code> if not implemented for the other type.
*/
final PyObject basebytes___lt__(PyObject other) {
int cmp = basebytes_cmp(other);
@@ -941,10 +950,10 @@
/**
* Implementation of __le__ (less than or equal to) operator, capable of comparison with another
- * byte array or bytes. Comparison with an invalid type returns null.
+ * byte array. Comparison with an invalid type returns <code>null</code>.
*
* @param other Python object to compare with
- * @return Python boolean result or null if not implemented for the other type.
+ * @return Python boolean result or <code>null</code> if not implemented for the other type.
*/
final PyObject basebytes___le__(PyObject other) {
int cmp = basebytes_cmp(other);
@@ -959,10 +968,10 @@
/**
* Implementation of __ge__ (greater than or equal to) operator, capable of comparison with
- * another byte array or bytes. Comparison with an invalid type returns null.
+ * another byte array. Comparison with an invalid type returns <code>null</code>.
*
* @param other Python object to compare with
- * @return Python boolean result or null if not implemented for the other type.
+ * @return Python boolean result or <code>null</code> if not implemented for the other type.
*/
final PyObject basebytes___ge__(PyObject other) {
int cmp = basebytes_cmp(other);
@@ -977,10 +986,10 @@
/**
* Implementation of __gt__ (greater than) operator, capable of comparison with another byte
- * array or bytes. Comparison with an invalid type returns null.
+ * array. Comparison with an invalid type returns <code>null</code>.
*
* @param other Python object to compare with
- * @return Python boolean result or null if not implemented for the other type.
+ * @return Python boolean result or <code>null</code> if not implemented for the other type.
*/
final PyObject basebytes___gt__(PyObject other) {
int cmp = basebytes_cmp(other);
@@ -1031,7 +1040,7 @@
* @param ostart of slice to search.
* @param oend of slice to search.
* @param endswith true if we are doing endswith, false if startswith.
- * @return true if and only if this bytearray ends with (one of) <code>target</code>.
+ * @return true if and only if this byte array ends with (one of) <code>target</code>.
*/
protected final synchronized boolean basebytes_starts_or_endswith(PyObject target,
PyObject ostart, PyObject oend, boolean endswith) {
@@ -1151,7 +1160,7 @@
* error policy. The returned PyObject will usually be a <code>PyUnicode</code>, but in practice
* it is whatever the <code>decode</code> method of the codec decides.
*
- * @param encoding the name of the codec (uses default codec if null)
+ * @param encoding the name of the codec (uses default codec if <code>null</code>)
* @return object containing the decoded characters
*/
public PyObject decode(String encoding) {
@@ -1163,8 +1172,8 @@
* policy. The returned PyObject will usually be a <code>PyUnicode</code>, but in practice it is
* whatever the <code>decode</code> method of the codec decides.
*
- * @param encoding the name of the codec (uses default codec if null)
- * @param errors the name of the error policy (uses 'strict' if null)
+ * @param encoding the name of the codec (uses default codec if <code>null</code>)
+ * @param errors the name of the error policy (uses 'strict' if <code>null</code>)
* @return object containing the decoded characters
*/
public PyObject decode(String encoding, String errors) {
@@ -1210,6 +1219,7 @@
*
* @return PyTuple that is first stage in pickling byte array
*/
+ @Override
public PyObject __reduce__() {
return basebytes___reduce__();
}
@@ -1555,6 +1565,7 @@
* the table is only 32 elements long, rather than (as it might be) 256 bytes, the number of
* distinct byte values.
*/
+ @Override
protected int[] calculateSkipTable() {
int[] skipTable = new int[MASK + 1];
int m = pattern.getLen();
@@ -1572,6 +1583,7 @@
*
* @return the new effective end of the text
*/
+ @Override
public int currIndex() {
return right + pattern.getLen() - 1;
}
@@ -1583,6 +1595,7 @@
*
* @return matching index or -1 if no (further) occurrences found
*/
+ @Override
public int nextIndex() {
int m = pattern.getLen();
@@ -1855,7 +1868,7 @@
*
* @param result to receive the decoded values
* @param hex specification of the bytes
- * @throws PyException(ValueError) if non-hex characters, or isolated ones, are encountered
+ * @throws PyException (ValueError) if non-hex characters, or isolated ones, are encountered
*/
static void basebytes_fromhex(BaseBytes result, String hex) throws PyException {
@@ -1937,7 +1950,7 @@
// Unsuitable object to be in this join
String fmt = "can only join an iterable of bytes (item %d has type '%.80s')";
throw Py.TypeError(String.format(fmt, iterList.size(), o.getType()
- .fastGetName()));
+ .fastGetName()));
}
iterList.add(v);
totalSize += v.getLen();
@@ -1990,6 +2003,9 @@
* the part before the separator, the separator itself, and the part after the separator. If the
* separator is not found, return a 3-tuple containing the string itself, followed by two empty
* byte arrays.
+ * <p>
+ * The elements of the <code>PyTuple</code> returned by this method are instances of the same
+ * actual type as <code>this</code>.
*
* @param sep the separator on which to partition this byte array
* @return a tuple of (head, separator, tail)
@@ -2000,6 +2016,9 @@
/**
* Ready-to-expose implementation of Python <code>partition(sep)</code>.
+ * <p>
+ * The elements of the <code>PyTuple</code> returned by this method are instances of the same
+ * actual type as <code>this</code>.
*
* @param sep the separator on which to partition this byte array
* @return a tuple of (head, separator, tail)
@@ -2032,6 +2051,9 @@
/**
* Construct return value for implementation of Python <code>partition(sep)</code> or
* <code>rpartition(sep)</code>, returns [0:p], [p:q], [q:]
+ * <p>
+ * The elements of the <code>PyTuple</code> returned by this method are instances of the same
+ * actual type as <code>this</code>.
*
* @param p start of separator
* @param q start of tail
@@ -2430,6 +2452,9 @@
* containing the part before the separator, the separator itself, and the part after the
* separator. If the separator is not found, return a 3-tuple containing two empty byte arrays,
* followed by the byte array itself.
+ * <p>
+ * The elements of the <code>PyTuple</code> returned by this method are instances of the same
+ * actual type as <code>this</code>.
*
* @param sep the separator on which to partition this byte array
* @return a tuple of (head, separator, tail)
@@ -2440,6 +2465,9 @@
/**
* Ready-to-expose implementation of Python <code>rpartition(sep)</code>.
+ * <p>
+ * The elements of the <code>PyTuple</code> returned by this method are instances of the same
+ * actual type as <code>this</code>.
*
* @param sep the separator on which to partition this byte array
* @return a tuple of (head, separator, tail)
@@ -2471,6 +2499,9 @@
/**
* Implementation of Python <code>rsplit()</code>, that returns a list of the words in the byte
* array, using whitespace as the delimiter. See {@link #rsplit(PyObject, int)}.
+ * <p>
+ * The elements of the <code>PyList</code> returned by this method are instances of the same
+ * actual type as <code>this</code>.
*
* @return PyList of byte arrays that result from the split
*/
@@ -2480,10 +2511,13 @@
/**
* Implementation of Python <code>rsplit(sep)</code>, that returns a list of the words in the
- * byte array, using sep as the delimiter. See {@link #rsplit(PyObject, int)} for the semantics
- * of the separator.
+ * byte array, using <code>sep</code> as the delimiter. See {@link #rsplit(PyObject, int)} for
+ * the semantics of the separator.
+ * <p>
+ * The elements of the <code>PyList</code> returned by this method are instances of the same
+ * actual type as <code>this</code>.
*
- * @param sep bytes, or object viewable as bytes, defining the separator
+ * @param sep <code>bytes</code>, or object viewable as bytes, defining the separator
* @return PyList of byte arrays that result from the split
*/
public PyList rsplit(PyObject sep) {
@@ -2492,22 +2526,26 @@
/**
* Implementation of Python <code>rsplit(sep, maxsplit)</code>, that returns a list of the words
- * in the byte array, using sep as the delimiter. If maxsplit is given, at most maxsplit splits
- * are done (thus, the list will have at most maxsplit+1 elements). If maxsplit is not
- * specified, then there is no limit on the number of splits (all possible splits are made).
+ * in the byte array, using <code>sep</code> as the delimiter. If <code>maxsplit</code> is
+ * given, at most <code>maxsplit</code> splits are done (thus, the list will have at most
+ * <code>maxsplit+1</code> elements). If <code>maxsplit</code> is not specified, then there is
+ * no limit on the number of splits (all possible splits are made).
* <p>
- * The semantics of sep and maxcount are identical to those of <code>split(sep, maxsplit)</code>
- * , except that splits are generated from the right (and pushed onto the front of the result
- * list). The result is only different from that of <code>split</code> if <code>maxcount</code>
- * limits the number of splits. For example,
+ * The semantics of <code>sep</code> and maxcount are identical to those of
+ * <code>split(sep, maxsplit)</code> , except that splits are generated from the right (and
+ * pushed onto the front of the result list). The result is only different from that of
+ * <code>split</code> if <code>maxcount</code> limits the number of splits. For example,
* <ul>
* <li><code>bytearray(b' 1 2 3 ').rsplit()</code> returns
* <code>[bytearray(b'1'), bytearray(b'2'), bytearray(b'3')]</code>, and</li>
* <li><code>bytearray(b' 1 2 3 ').rsplit(None, 1)</code> returns
* <code>[bytearray(b' 1 2'), bytearray(b'3')]</code></li>.
* </ul>
+ * <p>
+ * The elements of the <code>PyList</code> returned by this method are instances of the same
+ * actual type as <code>this</code>.
*
- * @param sep bytes, or object viewable as bytes, defining the separator
+ * @param sep <code>bytes</code>, or object viewable as bytes, defining the separator
* @param maxsplit maximum number of splits
* @return PyList of byte arrays that result from the split
*/
@@ -2517,10 +2555,13 @@
/**
* Ready-to-expose implementation of Python <code>rsplit(sep, maxsplit)</code>, that returns a
- * list of the words in the byte array, using sep as the delimiter. Use the defines whitespace
- * semantics if sep is null.
+ * list of the words in the byte array, using <code>sep</code> as the delimiter. Use the defines
+ * whitespace semantics if <code>sep</code> is <code>null</code>.
+ * <p>
+ * The elements of the <code>PyList</code> returned by this method are instances of the same
+ * actual type as <code>this</code>.
*
- * @param sep bytes, or object viewable as bytes, defining the separator
+ * @param sep <code>bytes</code>, or object viewable as bytes, defining the separator
* @param maxsplit maximum number of splits
* @return PyList of byte arrays that result from the split
*/
@@ -2534,11 +2575,15 @@
/**
* Implementation of Python <code>rsplit(sep, maxsplit)</code>, that returns a list of the words
- * in the byte array, using sep (which is not null) as the delimiter. If maxsplit>=0, at most
- * maxsplit splits are done (thus, the list will have at most maxsplit+1 elements). If
- * maxsplit<0, then there is no limit on the number of splits (all possible splits are made).
+ * in the byte array, using <code>sep</code> (which is not <code>null</code>) as the delimiter.
+ * If <code>maxsplit>=0</code>, at most <code>maxsplit</code> splits are done (thus, the list
+ * will have at most <code>maxsplit+1</code> elements). If <code>maxsplit<0</code>, then
+ * there is no limit on the number of splits (all possible splits are made).
+ * <p>
+ * The elements of the <code>PyList</code> returned by this method are instances of the same
+ * actual type as <code>this</code>.
*
- * @param sep bytes, or object viewable as bytes, defining the separator
+ * @param sep <code>bytes</code>, or object viewable as bytes, defining the separator
* @param maxsplit maximum number of splits
* @return PyList of byte arrays that result from the split
*/
@@ -2589,15 +2634,18 @@
/**
* Implementation of Python <code>rsplit(None, maxsplit)</code>, that returns a list of the
- * words in the byte array, using whitespace as the delimiter. If maxsplit is given, at most
- * maxsplit splits are done (thus, the list will have at most maxsplit+1 elements). If maxsplit
- * is not specified, then there is no limit on the number of splits (all possible splits are
- * made).
+ * words in the byte array, using whitespace as the delimiter. If <code>maxsplit</code> is
+ * given, at most <code>maxsplit</code> splits are done (thus, the list will have at most
+ * <code>maxsplit+1</code> elements). If maxsplit is not specified, then there is no limit on
+ * the number of splits (all possible splits are made).
* <p>
* Runs of consecutive whitespace are regarded as a single separator, and the result will
* contain no empty strings at the start or end if the string has leading or trailing
* whitespace. Consequently, splitting an empty string or a string consisting of just whitespace
- * with a None separator returns [].
+ * with a <code>None</code> separator returns [].
+ * <p>
+ * The elements of the <code>PyList</code> returned by this method are instances of the same
+ * actual type as <code>this/self</code>.
*
* @param maxsplit maximum number of splits
* @return PyList of byte arrays that result from the split
@@ -2648,6 +2696,9 @@
/**
* Implementation of Python <code>split()</code>, that returns a list of the words in the byte
* array, using whitespace as the delimiter. See {@link #split(PyObject, int)}.
+ * <p>
+ * The elements of the <code>PyList</code> returned by this method are instances of the same
+ * actual type as <code>this</code>.
*
* @return PyList of byte arrays that result from the split
*/
@@ -2657,10 +2708,13 @@
/**
* Implementation of Python <code>split(sep)</code>, that returns a list of the words in the
- * byte array, using sep as the delimiter. See {@link #split(PyObject, int)} for the semantics
- * of the separator.
+ * byte array, using <code>sep</code> as the delimiter. See {@link #split(PyObject, int)} for
+ * the semantics of the separator.
+ * <p>
+ * The elements of the <code>PyList</code> returned by this method are instances of the same
+ * actual type as <code>this</code>.
*
- * @param sep bytes, or object viewable as bytes, defining the separator
+ * @param sep <code>bytes</code>, or object viewable as bytes, defining the separator
* @return PyList of byte arrays that result from the split
*/
public PyList split(PyObject sep) {
@@ -2669,29 +2723,33 @@
/**
* Implementation of Python <code>split(sep, maxsplit)</code>, that returns a list of the words
- * in the byte array, using sep as the delimiter. If maxsplit is given, at most maxsplit splits
- * are done (thus, the list will have at most maxsplit+1 elements). If maxsplit is not
- * specified, then there is no limit on the number of splits (all possible splits are made).
+ * in the byte array, using <code>sep</code> as the delimiter. If <code>maxsplit</code> is
+ * given, at most <code>maxsplit</code> splits are done. (Thus, the list will have at most
+ * <code>maxsplit+1</code> elements). If <code>maxsplit</code> is not specified, then there is
+ * no limit on the number of splits (all possible splits are made).
* <p>
- * If sep is given, consecutive delimiters are not grouped together and are deemed to delimit
- * empty strings (for example, '1,,2'.split(',') returns ['1', '', '2']). The sep argument may
- * consist of multiple characters (for example, '1<>2<>3'.split('<>') returns ['1',
- * '2', '3']). Splitting an empty string with a specified separator returns [''].
+ * If <code>sep</code> is given, consecutive delimiters are not grouped together and are deemed
+ * to delimit empty strings (for example, <code>'1,,2'.split(',')</code> returns
+ * <code>['1', '', '2']</code>). The <code>sep</code> argument may consist of multiple
+ * characters (for example, <code>'1<>2<>3'.split('<>')</code> returns <code>['1',
+ * '2', '3']</code>). Splitting an empty string with a specified separator <code> ['']</code>.
* <p>
- * If sep is not specified or is None, a different splitting algorithm is applied: runs of
- * consecutive whitespace are regarded as a single separator, and the result will contain no
- * empty strings at the start or end if the string has leading or trailing whitespace.
- * Consequently, splitting an empty string or a string consisting of just whitespace with a None
- * separator returns []. For example,
- *
+ * If <code>sep</code> is not specified or is <code>None</code>, a different splitting algorithm
+ * is applied: runs of consecutive whitespace are regarded as a single separator, and the result
+ * will contain no empty strings at the start or end if the string has leading or trailing
+ * whitespace. Consequently, splitting an empty string or a string consisting of just whitespace
+ * with a <code>None</code> separator returns <code>[]</code>. For example,
* <ul>
* <li><code>bytearray(b' 1 2 3 ').split()</code> returns
* <code>[bytearray(b'1'), bytearray(b'2'), bytearray(b'3')]</code>, and</li>
* <li><code>bytearray(b' 1 2 3 ').split(None, 1)</code> returns
* <code>[bytearray(b'1'), bytearray(b'2 3 ')]</code>.</li>
* </ul>
+ * <p>
+ * The elements of the <code>PyList</code> returned by this method are instances of the same
+ * actual type as <code>this</code>.
*
- * @param sep bytes, or object viewable as bytes, defining the separator
+ * @param sep <code>bytes</code>, or object viewable as bytes, defining the separator
* @param maxsplit maximum number of splits
* @return PyList of byte arrays that result from the split
*/
@@ -2701,10 +2759,13 @@
/**
* Ready-to-expose implementation of Python <code>split(sep, maxsplit)</code>, that returns a
- * list of the words in the byte array, using sep as the delimiter. Use the defines whitespace
- * semantics if sep is null.
+ * list of the words in the byte array, using <code>sep</code> as the delimiter. Use the defines
+ * whitespace semantics if <code>sep</code> is <code>null</code>.
+ * <p>
+ * The elements of the <code>PyList</code> returned by this method are instances of the same
+ * actual type as <code>this</code>.
*
- * @param sep bytes, or object viewable as bytes, defining the separator
+ * @param sep <code>bytes</code>, or object viewable as bytes, defining the separator
* @param maxsplit maximum number of splits
* @return PyList of byte arrays that result from the split
*/
@@ -2718,11 +2779,15 @@
/**
* Implementation of Python <code>split(sep, maxsplit)</code>, that returns a list of the words
- * in the byte array, using sep (which is not null) as the delimiter. If maxsplit>=0, at most
- * maxsplit splits are done (thus, the list will have at most maxsplit+1 elements). If
- * maxsplit<0, then there is no limit on the number of splits (all possible splits are made).
+ * in the byte array, using <code>sep</code> (which is not <code>null</code>) as the delimiter.
+ * If <code>maxsplit>=0</code>, at most <code>maxsplit</code> splits are done (thus, the list
+ * will have at most <code>maxsplit+1</code> elements). If <code>maxsplit<0</code>, then
+ * there is no limit on the number of splits (all possible splits are made).
+ * <p>
+ * The elements of the <code>PyList</code> returned by this method are instances of the same
+ * actual type as <code>this</code>.
*
- * @param sep bytes, or object viewable as bytes, defining the separator
+ * @param sep <code>bytes</code>, or object viewable as bytes, defining the separator
* @param maxsplit maximum number of splits
* @return PyList of byte arrays that result from the split
*/
@@ -2763,14 +2828,18 @@
/**
* Implementation of Python <code>split(None, maxsplit)</code>, that returns a list of the words
- * in the byte array, using whitespace as the delimiter. If maxsplit is given, at most maxsplit
- * splits are done (thus, the list will have at most maxsplit+1 elements). If maxsplit is not
- * specified, then there is no limit on the number of splits (all possible splits are made).
+ * in the byte array, using whitespace as the delimiter. If <code>maxsplit</code> is given, at
+ * most maxsplit splits are done (thus, the list will have at most <code>maxsplit+1</code>
+ * elements). If <code>maxsplit</code> is not specified, then there is no limit on the number of
+ * splits (all possible splits are made).
* <p>
* Runs of consecutive whitespace are regarded as a single separator, and the result will
* contain no empty strings at the start or end if the string has leading or trailing
* whitespace. Consequently, splitting an empty string or a string consisting of just whitespace
- * with a None separator returns [].
+ * with a <code>None</code> separator returns [].
+ * <p>
+ * The elements of the <code>PyList</code> returned by this method are instances of the same
+ * actual type as <code>this</code>.
*
* @param maxsplit maximum number of splits
* @return PyList of byte arrays that result from the split
@@ -2815,6 +2884,9 @@
/**
* Implementation of Python <code>splitlines()</code>, returning a list of the lines in the byte
* array, breaking at line boundaries. Line breaks are not included in the resulting segments.
+ * <p>
+ * The elements of the <code>PyList</code> returned by this method are instances of the same
+ * actual type as <code>this</code>.
*
* @return List of segments
*/
@@ -2826,6 +2898,9 @@
* Implementation of Python <code>splitlines(keepends)</code>, returning a list of the lines in
* the string, breaking at line boundaries. Line breaks are not included in the resulting list
* unless <code>keepends</code> is true.
+ * <p>
+ * The elements of the <code>PyList</code> returned by this method are instances of the same
+ * actual type as <code>this</code>.
*
* @param keepends if true, include the end of line bytes(s)
* @return PyList of segments
@@ -2838,6 +2913,9 @@
* Ready-to-expose implementation of Python <code>splitlines(keepends)</code>, returning a list
* of the lines in the array, breaking at line boundaries. Line breaks are not included in the
* resulting list unless keepends is given and true.
+ * <p>
+ * The elements of the <code>PyList</code> returned by this method are instances of the same
+ * actual type as <code>this</code>.
*
* @param keepends if true, include the end of line bytes(s)
* @return List of segments
@@ -2888,7 +2966,7 @@
* byte.
*
* @param function name
- * @param fillchar or null
+ * @param fillchar or <code>null</code>
* @return
*/
protected static byte fillByteCheck(String function, String fillchar) {
@@ -2937,7 +3015,7 @@
* exactly the original object.)
*
* @param width desired
- * @param fillchar one-byte String to fill with, or null implying space
+ * @param fillchar one-byte String to fill with, or <code>null</code> implying space
* @return (possibly new) byte array containing the result
*/
final BaseBytes basebytes_center(int width, String fillchar) {
@@ -2958,7 +3036,7 @@
* exactly the original object.)
*
* @param width desired
- * @param fillchar one-byte String to fill with, or null implying space
+ * @param fillchar one-byte String to fill with, or <code>null</code> implying space
* @return (possibly new) byte array containing the result
*/
final BaseBytes basebytes_ljust(int width, String fillchar) {
@@ -2977,7 +3055,7 @@
* exactly the original object.)
*
* @param width desired
- * @param fillchar one-byte String to fill with, or null implying space
+ * @param fillchar one-byte String to fill with, or <code>null</code> implying space
* @return (possibly new) byte array containing the result
*/
final BaseBytes basebytes_rjust(int width, String fillchar) {
@@ -3323,7 +3401,8 @@
/**
* Java API equivalent of Python <code>capitalize()</code>. This method treats the bytes as
* Unicode pont codes and is consistent with Java's {@link Character#toUpperCase(char)} and
- * {@link Character#toLowerCase(char)}.
+ * {@link Character#toLowerCase(char)}. The <code>BaseBytes</code> returned by this method has
+ * the same actual type as <code>this/self</code>.
*
* @return a copy of the array with its first character capitalized and the rest lowercased.
*/
@@ -3332,7 +3411,9 @@
}
/**
- * Ready-to-expose implementation of Python <code>capitalize()</code>.
+ * Ready-to-expose implementation of Python <code>capitalize()</code>. The
+ * <code>BaseBytes</code> returned by this method has the same actual type as
+ * <code>this/self</code>.
*
* @return a copy of the array with its first character capitalized and the rest lowercased.
*/
@@ -3365,7 +3446,9 @@
/**
* Java API equivalent of Python <code>lower()</code>. This method treats the bytes as Unicode
- * pont codes and is consistent with Java's {@link Character#toLowerCase(char)}.
+ * pont codes and is consistent with Java's {@link Character#toLowerCase(char)}. The
+ * <code>BaseBytes</code> returned by this method has the same actual type as
+ * <code>this/self</code>.
*
* @return a copy of the array with all the cased characters converted to lowercase.
*/
@@ -3374,7 +3457,8 @@
}
/**
- * Ready-to-expose implementation of Python <code>lower()</code>.
+ * Ready-to-expose implementation of Python <code>lower()</code>. The <code>BaseBytes</code>
+ * returned by this method has the same actual type as <code>this/self</code>.
*
* @return a copy of the array with all the cased characters converted to lowercase.
*/
@@ -3397,7 +3481,8 @@
/**
* Java API equivalent of Python <code>swapcase()</code>. This method treats the bytes as
* Unicode pont codes and is consistent with Java's {@link Character#toUpperCase(char)} and
- * {@link Character#toLowerCase(char)}.
+ * {@link Character#toLowerCase(char)}. The <code>BaseBytes</code> returned by this method has
+ * the same actual type as <code>this/self</code>.
*
* @return a copy of the array with uppercase characters converted to lowercase and vice versa.
*/
@@ -3406,7 +3491,8 @@
}
/**
- * Ready-to-expose implementation of Python <code>swapcase()</code>.
+ * Ready-to-expose implementation of Python <code>swapcase()</code>. The <code>BaseBytes</code>
+ * returned by this method has the same actual type as <code>this/self</code>.
*
* @return a copy of the array with uppercase characters converted to lowercase and vice versa.
*/
@@ -3432,7 +3518,8 @@
* Java API equivalent of Python <code>title()</code>. The algorithm uses a simple
* language-independent definition of a word as groups of consecutive letters. The definition
* works in many contexts but it means that apostrophes in contractions and possessives form
- * word boundaries, which may not be the desired result.
+ * word boundaries, which may not be the desired result. The <code>BaseBytes</code> returned by
+ * this method has the same actual type as <code>this/self</code>.
*
* @return a titlecased version of the array where words start with an uppercase character and
* the remaining characters are lowercase.
@@ -3442,7 +3529,8 @@
}
/**
- * Ready-to-expose implementation of Python <code>title()</code>.
+ * Ready-to-expose implementation of Python <code>title()</code>. The <code>BaseBytes</code>
+ * returned by this method has the same actual type as <code>this/self</code>.
*
* @return a titlecased version of the array where words start with an uppercase character and
* the remaining characters are lowercase.
@@ -3481,7 +3569,8 @@
/**
* Java API equivalent of Python <code>upper()</code>. Note that
* <code>x.upper().isupper()</code> might be <code>false</code> if the array contains uncased
- * characters.
+ * characters. The <code>BaseBytes</code> returned by this method has the same actual type as
+ * <code>this/self</code>.
*
* @return a copy of the array with all the cased characters converted to uppercase.
*/
@@ -3490,7 +3579,8 @@
}
/**
- * Ready-to-expose implementation of Python <code>upper()</code>.
+ * Ready-to-expose implementation of Python <code>upper()</code>. The <code>BaseBytes</code>
+ * returned by this method has the same actual type as <code>this/self</code>.
*
* @return a copy of the array with all the cased characters converted to uppercase.
*/
@@ -3533,7 +3623,7 @@
*
* @param index of value in byte array
* @return the integer value at the index
- * @throws PyException(IndexError) if the index is outside the array bounds
+ * @throws PyException (IndexError) if the index is outside the array bounds
*/
public synchronized int intAt(int index) throws PyException {
indexCheck(index);
@@ -3599,7 +3689,7 @@
*/
private static final void appendHexEscape(StringBuilder buf, int c) {
buf.append("\\x").append(Character.forDigit((c & 0xf0) >> 4, 16))
- .append(Character.forDigit(c & 0xf, 16));
+ .append(Character.forDigit(c & 0xf, 16));
}
/**
@@ -3666,8 +3756,8 @@
*/
/**
- * Access to the bytearray (or bytes) as a {@link java.util.List}. The List interface supplied
- * by BaseBytes delegates to this object.
+ * Access to the byte array as a {@link java.util.List}. The List interface supplied by
+ * BaseBytes delegates to this object.
*/
protected final List<PyInteger> listDelegate = new AbstractList<PyInteger>() {
@@ -3689,9 +3779,9 @@
* Replaces the element at the specified position in this list with the specified element.
*
* @see java.util.AbstractList#set(int, java.lang.Object)
- * @throws PyException(TypeError) if actual class is immutable
- * @throws PyException(IndexError) if the index is outside the array bounds
- * @throws PyException(ValueError) if element<0 or element>255
+ * @throws PyException (TypeError) if actual class is immutable
+ * @throws PyException (IndexError) if the index is outside the array bounds
+ * @throws PyException (ValueError) if element<0 or element>255
*/
@Override
public PyInteger set(int index, PyInteger element) throws PyException {
@@ -3707,9 +3797,9 @@
* currently at that position and any subsequent elements to the right.
*
* @see java.util.AbstractList#add(int, java.lang.Object)
- * @throws PyException(IndexError) if the index is outside the array bounds
- * @throws PyException(ValueError) if element<0 or element>255
- * @throws PyException(TypeError) if the owning concrete subclass is immutable
+ * @throws PyException (IndexError) if the index is outside the array bounds
+ * @throws PyException (ValueError) if element<0 or element>255
+ * @throws PyException (TypeError) if the owning concrete subclass is immutable
*/
@Override
public void add(int index, PyInteger element) throws PyException {
@@ -3724,7 +3814,7 @@
* removed from the list.
*
* @see java.util.AbstractList#remove(int)
- * @throws PyException(IndexError) if the index is outside the array bounds
+ * @throws PyException (IndexError) if the index is outside the array bounds
*/
@Override
public PyInteger remove(int index) {
@@ -3737,11 +3827,12 @@
};
/**
- * Number of bytes in bytearray (or bytes) object.
+ * Number of bytes in <code>bytearray</code> (or <code>bytes</code>) object.
*
* @see java.util.List#size()
* @return Number of bytes in byte array.
* */
+ @Override
public int size() {
return size;
}
@@ -3749,6 +3840,7 @@
/*
* @see java.util.List#isEmpty()
*/
+ @Override
public boolean isEmpty() {
return size == 0;
}
@@ -3757,6 +3849,7 @@
* Returns true if this list contains the specified value. More formally, returns true if and
* only if this list contains at least one integer e such that o.equals(PyInteger(e)).
*/
+ @Override
public boolean contains(Object o) {
return listDelegate.contains(o);
}
@@ -3764,6 +3857,7 @@
/*
* @see java.util.List#iterator()
*/
+ @Override
public Iterator<PyInteger> iterator() {
return listDelegate.iterator();
}
@@ -3771,6 +3865,7 @@
/*
* @see java.util.List#toArray()
*/
+ @Override
public Object[] toArray() {
return listDelegate.toArray();
}
@@ -3778,6 +3873,7 @@
/*
* @see java.util.List#toArray(T[])
*/
+ @Override
public <T> T[] toArray(T[] a) {
return listDelegate.toArray(a);
}
@@ -3785,6 +3881,7 @@
/*
* @see java.util.List#add(java.lang.Object)
*/
+ @Override
public boolean add(PyInteger o) {
return listDelegate.add(o);
}
@@ -3792,6 +3889,7 @@
/*
* @see java.util.List#remove(java.lang.Object)
*/
+ @Override
public boolean remove(Object o) {
return listDelegate.remove(o);
}
@@ -3799,6 +3897,7 @@
/*
* @see java.util.List#containsAll(java.util.Collection)
*/
+ @Override
public boolean containsAll(Collection<?> c) {
return listDelegate.containsAll(c);
}
@@ -3806,6 +3905,7 @@
/*
* @see java.util.List#addAll(java.util.Collection)
*/
+ @Override
public boolean addAll(Collection<? extends PyInteger> c) {
return listDelegate.addAll(c);
}
@@ -3813,6 +3913,7 @@
/*
* @see java.util.List#addAll(int, java.util.Collection)
*/
+ @Override
public boolean addAll(int index, Collection<? extends PyInteger> c) {
return listDelegate.addAll(index, c);
}
@@ -3820,6 +3921,7 @@
/*
* @see java.util.List#removeAll(java.util.Collection)
*/
+ @Override
public boolean removeAll(Collection<?> c) {
return listDelegate.removeAll(c);
}
@@ -3827,6 +3929,7 @@
/*
* @see java.util.List#retainAll(java.util.Collection)
*/
+ @Override
public boolean retainAll(Collection<?> c) {
return listDelegate.retainAll(c);
}
@@ -3834,6 +3937,7 @@
/*
* @see java.util.List#clear()
*/
+ @Override
public void clear() {
listDelegate.clear();
}
@@ -3865,6 +3969,7 @@
/*
* @see java.util.List#hashCode()
*/
+ @Override
public int hashCode() {
return listDelegate.hashCode();
}
@@ -3872,6 +3977,7 @@
/*
* @see java.util.List#get(int)
*/
+ @Override
public PyInteger get(int index) {
return listDelegate.get(index);
}
@@ -3879,6 +3985,7 @@
/*
* @see java.util.List#set(int, java.lang.Object)
*/
+ @Override
public PyInteger set(int index, PyInteger element) {
return listDelegate.set(index, element);
}
@@ -3886,6 +3993,7 @@
/*
* @see java.util.List#add(int, java.lang.Object)
*/
+ @Override
public void add(int index, PyInteger element) {
listDelegate.add(index, element);
}
@@ -3893,6 +4001,7 @@
/*
* @see java.util.List#remove(int)
*/
+ @Override
public PyInteger remove(int index) {
return listDelegate.remove(index);
}
@@ -3900,6 +4009,7 @@
/*
* @see java.util.List#indexOf(java.lang.Object)
*/
+ @Override
public int indexOf(Object o) {
return listDelegate.indexOf(o);
}
@@ -3907,6 +4017,7 @@
/*
* @see java.util.List#lastIndexOf(java.lang.Object)
*/
+ @Override
public int lastIndexOf(Object o) {
return listDelegate.lastIndexOf(o);
}
@@ -3914,6 +4025,7 @@
/*
* @see java.util.List#listIterator()
*/
+ @Override
public ListIterator<PyInteger> listIterator() {
return listDelegate.listIterator();
}
@@ -3921,6 +4033,7 @@
/*
* @see java.util.List#listIterator(int)
*/
+ @Override
public ListIterator<PyInteger> listIterator(int index) {
return listDelegate.listIterator(index);
}
@@ -3928,6 +4041,7 @@
/*
* @see java.util.List#subList(int, int)
*/
+ @Override
public List<PyInteger> subList(int fromIndex, int toIndex) {
return listDelegate.subList(fromIndex, toIndex);
}
@@ -3986,8 +4100,8 @@
* It is intended the client call this method only once to get the result of a series of
* append operations. A second call to {@link #getCount()}, before any further appending,
* returns a zero-length array. This is to ensure that the same array is not given out
- * twice. However, {@link #getCount()} continues to return the number bytes accumuated until
- * an append next occurs.
+ * twice. However, {@link #getCount()} continues to return the number bytes accumulated
+ * until an append next occurs.
*
* @return an array containing the accumulated result
*/
@@ -4131,7 +4245,7 @@
* Every sub-class of BaseBytes overrides this method to return a <code>Builder<B></code>
* where <code>B</code> is (normally) that class's particular type, and it extends
* <code>Builder<B></code> so that {@link Builder#getResult()} produces an instance of
- * <code>B</code> from the contents..
+ * <code>B</code> from the contents.
*
* @param capacity of the <code>Builder<B></code> returned
* @return a <code>Builder<B></code> for the correct sub-class
diff --git a/src/org/python/core/PyByteArray.java b/src/org/python/core/PyByteArray.java
--- a/src/org/python/core/PyByteArray.java
+++ b/src/org/python/core/PyByteArray.java
@@ -12,26 +12,24 @@
import org.python.expose.MethodType;
/**
- * Partial implementation of Python bytearray. At the present stage of development, the class
- * provides:
- * <ul>
- * <li>constructors (both __init__ and the Java API constructors),</li>
- * <li>the slice operations (get, set and delete)</li>
- * <li>a <code>List<PyInteger></code> implementation for the Java API</li>
- * </ul>
- * and this is founded on a particular approach to storage management internally. However, the
- * implementation does not support the <code>memoryview</code> interface either for access or a a
- * source for its constructors although the signatures are present. The rich set of string-like
- * operations due a <code>bytearray</code> is not implemented.
- *
+ * Implementation of Python <code>bytearray</code> with a Java API that includes equivalents to most
+ * of the Python API. These Python equivalents accept a {@link PyObject} as argument, where you
+ * might have expected a <code>byte[]</code> or <code>PyByteArray</code>, in order to accommodate
+ * the full range of types accepted by the Python equivalent: usually, any <code>PyObject</code>
+ * that implements {@link BufferProtocol}, providing a one-dimensional array of bytes, is an
+ * acceptable argument. In the documentation, the reader will often see the terms "byte array" or
+ * "object viewable as bytes" instead of <code>bytearray</code> when this broader scope is intended.
+ * This may relate to parameters, or to the target object itself (in text that applies equally to
+ * base or sibling classes).
*/
@ExposedType(name = "bytearray", base = PyObject.class, doc = BuiltinDocs.bytearray_doc)
public class PyByteArray extends BaseBytes implements BufferProtocol {
+ /** The {@link PyType} of <code>bytearray</code>. */
public static final PyType TYPE = PyType.fromClass(PyByteArray.class);
/**
- * Create a zero-length Python bytearray of explicitly-specified sub-type
+ * Constructs a zero-length Python <code>bytearray</code> of explicitly-specified sub-type
*
* @param type explicit Jython type
*/
@@ -40,16 +38,16 @@
}
/**
- * Create a zero-length Python bytearray.
+ * Constructs a zero-length Python <code>bytearray</code>.
*/
public PyByteArray() {
super(TYPE);
}
/**
- * Create zero-filled Python bytearray of specified size.
+ * Constructs zero-filled Python <code>bytearray</code> of specified size.
*
- * @param size of bytearray
+ * @param size of <code>bytearray</code>
*/
public PyByteArray(int size) {
super(TYPE);
@@ -57,7 +55,7 @@
}
/**
- * Construct bytearray by copying values from int[].
+ * Constructs a <code>bytearray</code> by copying values from int[].
*
* @param value source of the bytes (and size)
*/
@@ -66,8 +64,8 @@
}
/**
- * Create a new array filled exactly by a copy of the contents of the source, which is a
- * bytearray (or bytes).
+ * Constructs a new array filled exactly by a copy of the contents of the source, which is a
+ * <code>bytearray</code> (or <code>bytes</code>).
*
* @param value source of the bytes (and size)
*/
@@ -77,7 +75,7 @@
}
/**
- * Create a new array filled exactly by a copy of the contents of the source, which is a
+ * Constructs a new array filled exactly by a copy of the contents of the source, which is a
* byte-oriented {@link PyBuffer}.
*
* @param value source of the bytes (and size)
@@ -88,7 +86,7 @@
}
/**
- * Create a new array filled exactly by a copy of the contents of the source, which is an
+ * Constructs a new array filled exactly by a copy of the contents of the source, which is an
* object supporting the Jython version of the PEP 3118 buffer API.
*
* @param value source of the bytes (and size)
@@ -99,7 +97,7 @@
}
/**
- * Create a new array filled from an iterable of PyObject. The iterable must yield objects
+ * Constructs a new array filled from an iterable of PyObject. The iterable must yield objects
* convertible to Python bytes (non-negative integers less than 256 or strings of length 1).
*
* @param value source of the bytes (and size)
@@ -110,8 +108,8 @@
}
/**
- * Create a new array by encoding a PyString argument to bytes. If the PyString is actually a
- * PyUnicode, the encoding must be explicitly specified.
+ * Constructs a new array by encoding a PyString argument to bytes. If the PyString is actually
+ * a PyUnicode, the encoding must be explicitly specified.
*
* @param arg primary argument from which value is taken
* @param encoding name of optional encoding (must be a string type)
@@ -123,12 +121,12 @@
}
/**
- * Create a new array by encoding a PyString argument to bytes. If the PyString is actually a
- * PyUnicode, the encoding must be explicitly specified.
+ * Constructs a new array by encoding a PyString argument to bytes. If the PyString is actually
+ * a PyUnicode, the encoding must be explicitly specified.
*
* @param arg primary argument from which value is taken
- * @param encoding name of optional encoding (may be null to select the default for this
- * installation)
+ * @param encoding name of optional encoding (may be <code>null</code> to select the default for
+ * this installation)
* @param errors name of optional errors policy
*/
public PyByteArray(PyString arg, String encoding, String errors) {
@@ -137,8 +135,8 @@
}
/**
- * Create a new array by encoding a PyString argument to bytes. If the PyString is actually a
- * PyUnicode, an exception is thrown saying that the encoding must be explicitly specified.
+ * Constructs a new array by encoding a PyString argument to bytes. If the PyString is actually
+ * a PyUnicode, an exception is thrown saying that the encoding must be explicitly specified.
*
* @param arg primary argument from which value is taken
*/
@@ -148,7 +146,8 @@
}
/**
- * Construct bytearray by re-using an array of byte as storage initialised by the client.
+ * Constructs a <code>bytearray</code> by re-using an array of byte as storage initialised by
+ * the client.
*
* @param storage pre-initialised with desired value: the caller should not keep a reference
*/
@@ -158,12 +157,13 @@
}
/**
- * Construct bytearray by re-using an array of byte as storage initialised by the client.
+ * Constructs a <code>bytearray</code> by re-using an array of byte as storage initialised by
+ * the client.
*
* @param storage pre-initialised with desired value: the caller should not keep a reference
* @param size number of bytes actually used
- * @throws IllegalArgumentException if the range [0:size] is not within the array bounds of
- * the storage.
+ * @throws IllegalArgumentException if the range [0:size] is not within the array bounds of the
+ * storage.
*/
PyByteArray(byte[] storage, int size) {
super(TYPE);
@@ -171,28 +171,26 @@
}
/**
- * Create a new bytearray object from an arbitrary Python object according to the same rules as
- * apply in Python to the bytearray() constructor:
+ * Constructs a new <code>bytearray</code> object from an arbitrary Python object according to
+ * the same rules as apply in Python to the <code>bytearray()</code> constructor:
* <ul>
- * <li>bytearray() Construct a zero-length bytearray (arg is null).</li>
- * <li>bytearray(int) Construct a zero-initialized bytearray of the given length.</li>
- * <li>bytearray(iterable_of_ints) Construct from iterable yielding integers in [0..255]</li>
- * <li>bytearray(string [, encoding [, errors] ]) Construct from a text string, optionally using
- * the specified encoding.</li>
- * <li>bytearray(unicode, encoding [, errors]) Construct from a unicode string using the
- * specified encoding.</li>
- * <li>bytearray(bytes_or_bytearray) Construct as a mutable copy of bytes or existing bytearray
- * object.</li>
+ * <li><code>bytearray()</code> Construct a zero-length <code>bytearray</code>.</li>
+ * <li><code>bytearray(int)</code> Construct a zero-initialized <code>bytearray</code> of the
+ * given length.</li>
+ * <li><code>bytearray(iterable_of_ints)</code> Construct from iterable yielding integers in
+ * [0..255]</li>
+ * <li><code>bytearray(buffer)</code> Construct by reading from any object implementing
+ * {@link BufferProtocol}, including <code>str/bytes</code> or another <code>bytearray</code>.</li>
* </ul>
* When it is necessary to specify an encoding, as in the Python signature
- * <code>bytearray(string, encoding[, errors])</code>, use the constructor
- * {@link #PyByteArray(PyString, String, String)}. If the PyString is actually a PyUnicode, an
- * encoding must be specified, and using this constructor will throw an exception about that.
+ * <code>bytearray(string, encoding [, errors])</code>, use the constructor
+ * {@link #PyByteArray(PyString, String, String)}. If the <code>PyString</code> is actually a
+ * <code>PyUnicode</code>, an encoding must be specified, and using this constructor will throw
+ * an exception about that.
*
- * @param arg primary argument from which value is taken (may be null)
- * @throws PyException in the same circumstances as bytearray(arg), TypeError for non-iterable,
- * non-integer argument type, and ValueError if iterables do not yield byte [0..255]
- * values.
+ * @param arg primary argument from which value is taken (may be <code>null</code>)
+ * @throws PyException (TypeError) for non-iterable,
+ * @throws PyException (ValueError) if iterables do not yield byte [0..255] values.
*/
public PyByteArray(PyObject arg) throws PyException {
super(TYPE);
@@ -284,18 +282,19 @@
}
}
- /* ============================================================================================
+ /*
+ * ============================================================================================
* API for org.python.core.PySequence
* ============================================================================================
*/
/**
- * Returns a slice of elements from this sequence as a PyByteArray.
+ * Returns a slice of elements from this sequence as a <code>PyByteArray</code>.
*
* @param start the position of the first element.
* @param stop one more than the position of the last element.
* @param step the step size.
- * @return a PyByteArray corresponding the the given range of elements.
+ * @return a <code>PyByteArray</code> corresponding the the given range of elements.
*/
@Override
protected synchronized PyByteArray getslice(int start, int stop, int step) {
@@ -333,8 +332,8 @@
}
/**
- * Returns a PyByteArray that repeats this sequence the given number of times, as in the
- * implementation of <tt>__mul__</tt> for strings.
+ * Returns a <code>PyByteArray</code> that repeats this sequence the given number of times, as
+ * in the implementation of <tt>__mul__</tt> for strings.
*
* @param count the number of times to repeat this.
* @return this byte array repeated count times.
@@ -347,8 +346,8 @@
}
/**
- * Replace the contents of this PyByteArray with the given number of repeats of the original
- * contents, as in the implementation of <tt>__mul__</tt> for strings.
+ * Replace the contents of this <code>PyByteArray</code> with the given number of repeats of the
+ * original contents, as in the implementation of <tt>__mul__</tt> for strings.
*
* @param count the number of times to repeat this.
*/
@@ -357,35 +356,36 @@
}
/**
- * Sets the indexed element of the bytearray to the given value. This is an extension point
- * called by PySequence in its implementation of {@link #__setitem__} It is guaranteed by
- * PySequence that the index is within the bounds of the array. Any other clients calling
- * <tt>pyset(int)</tt> must make the same guarantee.
+ * Sets the indexed element of the <code>bytearray</code> to the given value. This is an
+ * extension point called by PySequence in its implementation of {@link #__setitem__} It is
+ * guaranteed by PySequence that the index is within the bounds of the array. Any other clients
+ * calling <code>pyset(int)</code> must make the same guarantee.
*
* @param index index of the element to set.
* @param value the value to set this element to.
- * @throws PyException(AttributeError) if value cannot be converted to an integer
- * @throws PyException(ValueError) if value<0 or value>255
+ * @throws PyException (AttributeError) if value cannot be converted to an integer
+ * @throws PyException (ValueError) if value<0 or value>255
*/
+ @Override
public synchronized void pyset(int index, PyObject value) throws PyException {
storage[index + offset] = byteCheck(value);
}
/**
- * Insert the element (interpreted as a Python byte value) at the given index.
- * Python int, long and string types of length 1 are allowed.
+ * Insert the element (interpreted as a Python byte value) at the given index. Python
+ * <code>int</code>, <code>long</code> and <code>str</code> types of length 1 are allowed.
*
* @param index to insert at
* @param element to insert (by value)
- * @throws PyException(IndexError) if the index is outside the array bounds
- * @throws PyException(ValueError) if element<0 or element>255
- * @throws PyException(TypeError) if the subclass is immutable
+ * @throws PyException (IndexError) if the index is outside the array bounds
+ * @throws PyException (ValueError) if element<0 or element>255
+ * @throws PyException (TypeError) if the subclass is immutable
*/
@Override
public synchronized void pyinsert(int index, PyObject element) {
// Open a space at the right location.
storageReplace(index, 0, 1);
- storage[offset+index] = byteCheck(element);
+ storage[offset + index] = byteCheck(element);
}
/**
@@ -398,9 +398,10 @@
* of exactly that many elements (or convertible to such a sequence).
* <p>
* When assigning from a sequence type or iterator, the sequence may contain arbitrary
- * <code>PyObject</code>s, but acceptable ones are PyInteger, PyLong or PyString of length 1. If
- * any one of them proves unsuitable for assignment to a Python bytarray element, an exception
- * is thrown and this bytearray is unchanged.
+ * {@link PyObject}s, but acceptable ones are {@link PyInteger}, {@link PyLong} or
+ * {@link PyString} of length 1. If any one of them proves unsuitable for assignment to a Python
+ * <code>bytearray</code> element, an exception is thrown and this <code>bytearray</code> is
+ * unchanged.
*
* <pre>
* a = bytearray(b'abcdefghijklmnopqrst')
@@ -472,14 +473,14 @@
/**
* Sets the given range of elements according to Python slice assignment semantics from a
- * zero-filled bytearray of the given length.
+ * zero-filled <code>bytearray</code> of the given length.
*
* @see #setslice(int, int, int, PyObject)
* @param start the position of the first element.
* @param stop one more than the position of the last element.
* @param step the step size.
* @param len number of zeros to insert consistent with the slice assignment
- * @throws PyException(SliceSizeError) if the value size is inconsistent with an extended slice
+ * @throws PyException (SliceSizeError) if the value size is inconsistent with an extended slice
*/
private void setslice(int start, int stop, int step, int len) throws PyException {
if (step == 1) {
@@ -501,14 +502,14 @@
/**
* Sets the given range of elements according to Python slice assignment semantics from a
- * PyString.
+ * {@link PyString}.
*
* @see #setslice(int, int, int, PyObject)
* @param start the position of the first element.
* @param stop one more than the position of the last element.
* @param step the step size.
* @param value a PyString object consistent with the slice assignment
- * @throws PyException(SliceSizeError) if the value size is inconsistent with an extended slice
+ * @throws PyException (SliceSizeError) if the value size is inconsistent with an extended slice
*/
private void setslice(int start, int stop, int step, PyString value) throws PyException {
String v = value.asString();
@@ -536,7 +537,7 @@
* @param stop one more than the position of the last element.
* @param step the step size.
* @param value an object supporting the buffer API consistent with the slice assignment
- * @throws PyException(SliceSizeError) if the value size is inconsistent with an extended slice
+ * @throws PyException (SliceSizeError) if the value size is inconsistent with an extended slice
*/
private void setslice(int start, int stop, int step, BufferProtocol value) throws PyException {
@@ -547,7 +548,7 @@
if (step == 1) {
// Delete this[start:stop] and open a space of the right size
storageReplace(start, stop - start, len);
- view.copyTo(storage, start+offset);
+ view.copyTo(storage, start + offset);
} else {
// This is an extended slice which means we are replacing elements
@@ -564,14 +565,14 @@
/**
* Sets the given range of elements according to Python slice assignment semantics from a
- * bytearray (or bytes).
+ * <code>bytearray</code> (or bytes).
*
* @see #setslice(int, int, int, PyObject)
* @param start the position of the first element.
* @param stop one more than the position of the last element.
* @param step the step size.
- * @param value a bytearray (or bytes) object consistent with the slice assignment
- * @throws PyException(SliceSizeError) if the value size is inconsistent with an extended slice
+ * @param value a <code>bytearray</code> (or bytes) object consistent with the slice assignment
+ * @throws PyException (SliceSizeError) if the value size is inconsistent with an extended slice
*/
private void setslice(int start, int stop, int step, BaseBytes value) throws PyException {
@@ -603,14 +604,14 @@
/**
* Sets the given range of elements according to Python slice assignment semantics from a
- * bytearray (or bytes).
+ * <code>bytearray</code> (or bytes).
*
* @see #setslice(int, int, int, PyObject)
* @param start the position of the first element.
* @param stop one more than the position of the last element.
* @param step the step size.
* @param iter iterable source of values to enter in the array
- * @throws PyException(SliceSizeError) if the iterable size is inconsistent with an extended
+ * @throws PyException (SliceSizeError) if the iterable size is inconsistent with an extended
* slice
*/
private void setslice(int start, int stop, int step, Iterable<? extends PyObject> iter) {
@@ -640,21 +641,12 @@
}
}
-// Idiom:
-// if (step == 1) {
-// // Do something efficient with block start...stop-1
-// } else {
-// int n = sliceLength(start, stop, step);
-// for (int i = start, j = 0; j < n; i += step, j++) {
-// // Perform jth operation with element i
-// }
-// }
-
/*
* Deletes an element from the sequence (and closes up the gap).
*
* @param index index of the element to delete.
*/
+ @Override
protected synchronized void del(int index) {
// XXX Change SequenceIndexDelegate to avoid repeated calls to del(int) for extended slice
storageDelete(index, 1);
@@ -667,6 +659,7 @@
*
* @param stop one more than the position of the last element.
*/
+ @Override
protected synchronized void delRange(int start, int stop) {
storageDelete(start, stop - start);
}
@@ -714,29 +707,29 @@
}
/**
- * Initialise a mutable bytearray object from various arguments. This single initialisation must
- * support:
+ * Initialise a mutable <code>bytearray</code> object from various arguments. This single
+ * initialisation must support:
* <ul>
- * <li>bytearray() Construct a zero-length bytearray.</li>
- * <li>bytearray(int) Construct a zero-initialized bytearray of the given length.</li>
- * <li>bytearray(iterable_of_ints) Construct from iterable yielding integers in [0..255]</li>
- * <li>bytearray(string [, encoding [, errors] ]) Construct from a text string, optionally using
+ * <li><code>bytearray()</code> Construct a zero-length <code>bytearray</code>.</li>
+ * <li><code>bytearray(int)</code> Construct a zero-initialized <code>bytearray</code> of the
+ * given length.</li>
+ * <li><code>bytearray(iterable_of_ints)</code> Construct from iterable yielding integers in
+ * [0..255]</li>
+ * <li><code>bytearray(buffer)</code> Construct by reading from any object implementing
+ * {@link BufferProtocol}, including <code>str/bytes</code> or another <code>bytearray</code>.</li>
+ * <li><code>bytearray(string, encoding [, errors])</code> Construct from a
+ * <code>str/bytes</code>, decoded using the system default encoding, and encoded to bytes using
* the specified encoding.</li>
- * <li>bytearray(unicode, encoding [, errors]) Construct from a unicode string using the
- * specified encoding.</li>
- * <li>bytearray(bytes_or_bytearray) Construct as a mutable copy of bytes or existing bytearray
- * object.</li>
+ * <li><code>bytearray(unicode, encoding [, errors])</code> Construct from a
+ * <code>unicode</code> string, encoded to bytes using the specified encoding.</li>
* </ul>
- * Unlike CPython we are not able to support the initialisation: <li>bytearray(memory_view)
- * Construct as copy of any object implementing the buffer API.</li> </ul> Although effectively
- * a constructor, it is possible to call __init__ on a 'used' object so the method does not
- * assume any particular prior state.
+ * Although effectively a constructor, it is possible to call <code>__init__</code> on a 'used'
+ * object so the method does not assume any particular prior state.
*
* @param args argument array according to Jython conventions
* @param kwds Keywords according to Jython conventions
- * @throws PyException in the same circumstances as bytearray(arg), TypeError for non-iterable,
- * non-integer argument type, and ValueError if iterables do not yield byte [0..255]
- * values.
+ * @throws PyException (TypeError) for non-iterable,
+ * @throws PyException (ValueError) if iterables do not yield byte [0..255] values.
*/
@ExposedNew
@ExposedMethod(doc = BuiltinDocs.bytearray___init___doc)
@@ -795,7 +788,8 @@
};
}
- /* ============================================================================================
+ /*
+ * ============================================================================================
* Python API rich comparison operations
* ============================================================================================
*/
@@ -830,8 +824,6 @@
return basebytes___gt__(other);
}
-
-
@ExposedMethod(type = MethodType.BINARY, doc = BuiltinDocs.bytearray___eq___doc)
final synchronized PyObject bytearray___eq__(PyObject other) {
return basebytes___eq__(other);
@@ -862,7 +854,8 @@
return basebytes___gt__(other);
}
-/* ============================================================================================
+/*
+ * ============================================================================================
* Python API for bytearray
* ============================================================================================
*/
@@ -876,10 +869,8 @@
final synchronized PyObject bytearray___add__(PyObject o) {
PyByteArray sum = null;
-
// XXX re-write using buffer API
-
if (o instanceof BaseBytes) {
BaseBytes ob = (BaseBytes)o;
// Quick route: allocate the right size bytearray and copy the two parts in.
@@ -985,7 +976,7 @@
* length 1.
*
* @param element the item to append.
- * @throws PyException(ValueError) if element<0 or element>255
+ * @throws PyException (ValueError) if element<0 or element>255
*/
public void append(PyObject element) {
bytearray_append(element);
@@ -1002,9 +993,10 @@
* Implement to the standard Python __contains__ method, which in turn implements the
* <code>in</code> operator.
*
- * @param o the element to search for in this bytearray.
+ * @param o the element to search for in this <code>bytearray</code>.
* @return the result of the search.
**/
+ @Override
public boolean __contains__(PyObject o) {
return basebytes___contains__(o);
}
@@ -1038,7 +1030,7 @@
* <code>width</code> is less than <code>this.size()</code>.
*
* @param width desired
- * @param fillchar one-byte String to fill with, or null implying space
+ * @param fillchar one-byte String to fill with, or <code>null</code> implying space
* @return new byte array containing the result
*/
public PyByteArray center(int width, String fillchar) {
@@ -1097,11 +1089,11 @@
* Implementation of Python <code>endswith(suffix)</code>.
*
* When <code>suffix</code> is of a type that may be treated as an array of bytes, return
- * <code>true</code> if and only if this bytearray ends with the <code>suffix</code>.
- * <code>suffix</code> can also be a tuple of suffixes to look for.
+ * <code>true</code> if and only if this <code>bytearray</code> ends with the
+ * <code>suffix</code>. <code>suffix</code> can also be a tuple of suffixes to look for.
*
* @param suffix byte array to match, or object viewable as such, or a tuple of them
- * @return true if and only if this bytearray ends with the suffix (or one of them)
+ * @return true if and only if this <code>bytearray</code> ends with the suffix (or one of them)
*/
public boolean endswith(PyObject suffix) {
return basebytes_starts_or_endswith(suffix, null, null, true);
@@ -1111,13 +1103,14 @@
* Implementation of Python <code>endswith( suffix [, start ] )</code>.
*
* When <code>suffix</code> is of a type that may be treated as an array of bytes, return
- * <code>true</code> if and only if this bytearray ends with the <code>suffix</code>.
- * <code>suffix</code> can also be a tuple of suffixes to look for. With optional
- * <code>start</code> (which may be <code>null</code> or <code>Py.None</code>), define the
- * effective bytearray to be the slice <code>[start:]</code> of this bytearray.
+ * <code>true</code> if and only if this <code>bytearray</code> ends with the
+ * <code>suffix</code>. <code>suffix</code> can also be a tuple of suffixes to look for. With
+ * optional <code>start</code> (which may be <code>null</code> or <code>Py.None</code>), define
+ * the effective <code>bytearray</code> to be the slice <code>[start:]</code> of this
+ * <code>bytearray</code>.
*
* @param suffix byte array to match, or object viewable as such, or a tuple of them
- * @param start of slice in this bytearray to match
+ * @param start of slice in this <code>bytearray</code> to match
* @return true if and only if this[start:] ends with the suffix (or one of them)
*/
public boolean endswith(PyObject suffix, PyObject start) {
@@ -1128,15 +1121,15 @@
* Implementation of Python <code>endswith( suffix [, start [, end ]] )</code>.
*
* When <code>suffix</code> is of a type that may be treated as an array of bytes, return
- * <code>true</code> if and only if this bytearray ends with the <code>suffix</code>.
- * <code>suffix</code> can also be a tuple of suffixes to look for. With optional
- * <code>start</code> and <code>end</code> (which may be <code>null</code> or
- * <code>Py.None</code>), define the effective bytearray to be the slice
- * <code>[start:end]</code> of this bytearray.
+ * <code>true</code> if and only if this <code>bytearray</code> ends with the
+ * <code>suffix</code>. <code>suffix</code> can also be a tuple of suffixes to look for. With
+ * optional <code>start</code> and <code>end</code> (which may be <code>null</code> or
+ * <code>Py.None</code>), define the effective <code>bytearray</code> to be the slice
+ * <code>[start:end]</code> of this <code>bytearray</code>.
*
* @param suffix byte array to match, or object viewable as such, or a tuple of them
- * @param start of slice in this bytearray to match
- * @param end of slice in this bytearray to match
+ * @param start of slice in this <code>bytearray</code> to match
+ * @param end of slice in this <code>bytearray</code> to match
* @return true if and only if this[start:end] ends with the suffix (or one of them)
*/
public boolean endswith(PyObject suffix, PyObject start, PyObject end) {
@@ -1180,7 +1173,7 @@
/**
* Append the elements in the argument sequence to the end of the array, equivalent to:
- * <code>s[len(s):len(s)] = o</code>. The argument must be a subclass of BaseBytes or an
+ * <code>s[len(s):len(s)] = o</code>. The argument must be a subclass of {@link BaseBytes} or an
* iterable type returning elements compatible with byte assignment.
*
* @param o the sequence of items to append to the list.
@@ -1192,7 +1185,7 @@
@ExposedMethod(doc = BuiltinDocs.bytearray_extend_doc)
final synchronized void bytearray_extend(PyObject o) {
// Use the general method, assigning to the crack at the end of the array.
- // Note this deals with all legitimate PyObject types and the case o==this.
+ // Note this deals with all legitimate PyObject types including the case o==this.
setslice(size, size, 1, o);
}
@@ -1253,7 +1246,7 @@
* </pre>
*
* @param hex specification of the bytes
- * @throws PyException(ValueError) if non-hex characters, or isolated ones, are encountered
+ * @throws PyException (ValueError) if non-hex characters, or isolated ones, are encountered
*/
static PyByteArray fromhex(String hex) throws PyException {
return bytearray_fromhex(TYPE, hex);
@@ -1322,9 +1315,11 @@
/**
* This type is not hashable.
+ *
+ * @throws PyException (TypeError) as this type is not hashable.
*/
@Override
- public int hashCode() {
+ public int hashCode() throws PyException {
return bytearray___hash__();
}
@@ -1443,10 +1438,10 @@
return (PyByteArray)basebytes_upper();
}
- /**
- * Implementation of Python <code>join(iterable)</code>. Return a bytearray which is the
- * concatenation of the byte arrays in the iterable <code>iterable</code>. The separator between
- * elements is the byte array providing this method.
+ /**
+ * Implementation of Python <code>join(iterable)</code>. Return a <code>bytearray</code> which
+ * is the concatenation of the byte arrays in the iterable <code>iterable</code>. The separator
+ * between elements is the byte array providing this method.
*
* @param iterable of byte array objects, or objects viewable as such.
* @return byte array produced by concatenation.
@@ -1484,7 +1479,7 @@
* <code>width</code> is less than <code>this.size()</code>.
*
* @param width desired
- * @param fillchar one-byte String to fill with, or null implying space
+ * @param fillchar one-byte String to fill with, or <code>null</code> implying space
* @return new byte array containing the result
*/
public PyByteArray ljust(int width, String fillchar) {
@@ -1498,8 +1493,8 @@
}
/**
- * Implementation of Python <code>lstrip()</code>. Return a copy of the byte array with the leading
- * whitespace characters removed.
+ * Implementation of Python <code>lstrip()</code>. Return a copy of the byte array with the
+ * leading whitespace characters removed.
*
* @return a byte array containing this value stripped of those bytes
*/
@@ -1510,10 +1505,10 @@
/**
* Implementation of Python <code>lstrip(bytes)</code>
*
- * Return a copy of the byte array with the leading characters removed. The bytes
- * argument is an object specifying the set of characters to be removed. If null or None, the
- * bytes argument defaults to removing whitespace. The bytes argument is not a prefix;
- * rather, all combinations of its values are stripped.
+ * Return a copy of the byte array with the leading characters removed. The bytes argument is an
+ * object specifying the set of characters to be removed. If <code>null</code> or
+ * <code>None</code>, the bytes argument defaults to removing whitespace. The bytes argument is
+ * not a prefix; rather, all combinations of its values are stripped.
*
* @param bytes treated as a set of bytes defining what values to strip
* @return a byte array containing this value stripped of those bytes (at the left)
@@ -1542,7 +1537,8 @@
}
/**
- * Removes and return the last element in the byte array.
+ * Remove and return the last element in the byte array.
+ *
* @return PyInteger representing the value
*/
public PyInteger pop() {
@@ -1584,7 +1580,7 @@
* argument must be a PyInteger, PyLong or string of length 1.
*
* @param o the value to remove from the list.
- * @throws PyException ValueError if o not found in bytearray
+ * @throws PyException ValueError if o not found in <code>bytearray</code>
*/
public void remove(PyObject o) throws PyException {
bytearray_remove(o);
@@ -1746,7 +1742,7 @@
* <code>width</code> is less than <code>this.size()</code>.
*
* @param width desired
- * @param fillchar one-byte String to fill with, or null implying space
+ * @param fillchar one-byte String to fill with, or <code>null</code> implying space
* @return new byte array containing the result
*/
public PyByteArray rjust(int width, String fillchar) {
@@ -1793,7 +1789,8 @@
}
/**
- * Implementation of Python <code>rstrip()</code>. Return a copy of the byte array with the trailing whitespace characters removed.
+ * Implementation of Python <code>rstrip()</code>. Return a copy of the byte array with the
+ * trailing whitespace characters removed.
*
* @return a byte array containing this value stripped of those bytes (at right)
*/
@@ -1804,10 +1801,10 @@
/**
* Implementation of Python <code>rstrip(bytes)</code>
*
- * Return a copy of the byte array with the trailing characters removed. The bytes
- * argument is an object specifying the set of characters to be removed. If null or None, the
- * bytes argument defaults to removing whitespace. The bytes argument is not a suffix;
- * rather, all combinations of its values are stripped.
+ * Return a copy of the byte array with the trailing characters removed. The bytes argument is
+ * an object specifying the set of characters to be removed. If <code>null</code> or
+ * <code>None</code>, the bytes argument defaults to removing whitespace. The bytes argument is
+ * not a suffix; rather, all combinations of its values are stripped.
*
* @param bytes treated as a set of bytes defining what values to strip
* @return a byte array containing this value stripped of those bytes (at right)
@@ -1844,11 +1841,12 @@
* Implementation of Python <code>startswith(prefix)</code>.
*
* When <code>prefix</code> is of a type that may be treated as an array of bytes, return
- * <code>true</code> if and only if this bytearray starts with the <code>prefix</code>.
- * <code>prefix</code> can also be a tuple of prefixes to look for.
+ * <code>true</code> if and only if this <code>bytearray</code> starts with the
+ * <code>prefix</code>. <code>prefix</code> can also be a tuple of prefixes to look for.
*
* @param prefix byte array to match, or object viewable as such, or a tuple of them
- * @return true if and only if this bytearray starts with the prefix (or one of them)
+ * @return true if and only if this <code>bytearray</code> starts with the prefix (or one of
+ * them)
*/
public boolean startswith(PyObject prefix) {
return basebytes_starts_or_endswith(prefix, null, null, false);
@@ -1858,13 +1856,14 @@
* Implementation of Python <code>startswith( prefix [, start ] )</code>.
*
* When <code>prefix</code> is of a type that may be treated as an array of bytes, return
- * <code>true</code> if and only if this bytearray starts with the <code>prefix</code>.
- * <code>prefix</code> can also be a tuple of prefixes to look for. With optional
- * <code>start</code> (which may be <code>null</code> or <code>Py.None</code>), define the
- * effective bytearray to be the slice <code>[start:]</code> of this bytearray.
+ * <code>true</code> if and only if this <code>bytearray</code> starts with the
+ * <code>prefix</code>. <code>prefix</code> can also be a tuple of prefixes to look for. With
+ * optional <code>start</code> (which may be <code>null</code> or <code>Py.None</code>), define
+ * the effective <code>bytearray</code> to be the slice <code>[start:]</code> of this
+ * <code>bytearray</code>.
*
* @param prefix byte array to match, or object viewable as such, or a tuple of them
- * @param start of slice in this bytearray to match
+ * @param start of slice in this <code>bytearray</code> to match
* @return true if and only if this[start:] starts with the prefix (or one of them)
*/
public boolean startswith(PyObject prefix, PyObject start) {
@@ -1875,15 +1874,15 @@
* Implementation of Python <code>startswith( prefix [, start [, end ]] )</code>.
*
* When <code>prefix</code> is of a type that may be treated as an array of bytes, return
- * <code>true</code> if and only if this bytearray starts with the <code>prefix</code>.
- * <code>prefix</code> can also be a tuple of prefixes to look for. With optional
- * <code>start</code> and <code>end</code> (which may be <code>null</code> or
- * <code>Py.None</code>), define the effective bytearray to be the slice
- * <code>[start:end]</code> of this bytearray.
+ * <code>true</code> if and only if this <code>bytearray</code> starts with the
+ * <code>prefix</code>. <code>prefix</code> can also be a tuple of prefixes to look for. With
+ * optional <code>start</code> and <code>end</code> (which may be <code>null</code> or
+ * <code>Py.None</code>), define the effective <code>bytearray</code> to be the slice
+ * <code>[start:end]</code> of this <code>bytearray</code>.
*
* @param prefix byte array to match, or object viewable as such, or a tuple of them
- * @param start of slice in this bytearray to match
- * @param end of slice in this bytearray to match
+ * @param start of slice in this <code>bytearray</code> to match
+ * @param end of slice in this <code>bytearray</code> to match
* @return true if and only if this[start:end] starts with the prefix (or one of them)
*/
public boolean startswith(PyObject prefix, PyObject start, PyObject end) {
@@ -1896,8 +1895,8 @@
}
/**
- * Implementation of Python <code>strip()</code>. Return a copy of the byte array with the leading
- * and trailing whitespace characters removed.
+ * Implementation of Python <code>strip()</code>. Return a copy of the byte array with the
+ * leading and trailing whitespace characters removed.
*
* @return a byte array containing this value stripped of those bytes (left and right)
*/
@@ -1909,9 +1908,10 @@
* Implementation of Python <code>strip(bytes)</code>
*
* Return a copy of the byte array with the leading and trailing characters removed. The bytes
- * argument is anbyte arrayt specifying the set of characters to be removed. If null or None, the
- * bytes argument defaults to removing whitespace. The bytes argument is not a prefix or suffix;
- * rather, all combinations of its values are stripped.
+ * argument is anbyte arrayt specifying the set of characters to be removed. If
+ * <code>null</code> or <code>None</code>, the bytes argument defaults to removing whitespace.
+ * The bytes argument is not a prefix or suffix; rather, all combinations of its values are
+ * stripped.
*
* @param bytes treated as a set of bytes defining what values to strip
* @return a byte array containing this value stripped of those bytes (left and right)
@@ -1980,13 +1980,13 @@
* Implementation of Python <code>translate(table).</code>
*
* Return a copy of the byte array where all bytes occurring in the optional argument
- * <code>deletechars</code> are removed, and the remaining bytes have been mapped through the given
- * translation table, which must be of length 256.
+ * <code>deletechars</code> are removed, and the remaining bytes have been mapped through the
+ * given translation table, which must be of length 256.
*
* @param table length 256 translation table (of a type that may be regarded as a byte array)
* @return translated byte array
*/
- public PyByteArray translate(PyObject table) {
+ public PyByteArray translate(PyObject table) {
return bytearray_translate(table, null);
}
@@ -1994,12 +1994,12 @@
* Implementation of Python <code>translate(table[, deletechars]).</code>
*
* Return a copy of the byte array where all bytes occurring in the optional argument
- * <code>deletechars</code> are removed, and the remaining bytes have been mapped through the given
- * translation table, which must be of length 256.
+ * <code>deletechars</code> are removed, and the remaining bytes have been mapped through the
+ * given translation table, which must be of length 256.
*
- * You can use the maketrans() helper function in the string module to create a translation
- * table. For string objects, set the table argument to None for translations that only delete
- * characters:
+ * You can use the Python <code>maketrans()</code> helper function in the <code>string</code>
+ * module to create a translation table. For string objects, set the table argument to
+ * <code>None</code> for translations that only delete characters:
*
* @param table length 256 translation table (of a type that may be regarded as a byte array)
* @param deletechars object that may be regarded as a byte array, defining bytes to delete
@@ -2131,6 +2131,7 @@
*
* @param needed becomes the new value of this.size
*/
+ @Override
protected void newStorage(int needed) {
if (needed > 0) {
final int L = recLength(needed);
@@ -2168,7 +2169,7 @@
* been preserved, although probably moved, and the gap between them has been adjusted to the
* requested size.
* <p>
- * The effect on this PyByteArray is that:
+ * The effect on this <code>PyByteArray</code> is that:
*
* <pre>
* this.offset = f'
@@ -2277,7 +2278,8 @@
* where the regions of length <code>a</code> and <code>b=size-(a+d)</code> have been preserved
* and the gap between them adjusted to specification. The new offset f' is chosen heuristically
* by the method to optimise the efficiency of repeated adjustment near either end of the array,
- * e.g. repeated prepend or append operations. The effect on this PyByteArray is that:
+ * e.g. repeated prepend or append operations. The effect on this <code>PyByteArray</code> is
+ * that:
*
* <pre>
* this.offset = f'
@@ -2357,7 +2359,8 @@
* where the regions of length <code>a</code> and <code>b=size-(a+d)</code> have been preserved
* and the gap between them adjusted to specification. The new offset f' is chosen heuristically
* by the method to optimise the efficiency of repeated adjustment near either end of the array,
- * e.g. repeated prepend or append operations. The effect on this PyByteArray is that:
+ * e.g. repeated prepend or append operations. The effect on this <code>PyByteArray</code> is
+ * that:
*
* <pre>
* this.offset = f'
@@ -2439,7 +2442,7 @@
*
* where the contents of region <code>a</code> have been preserved, although possbly moved, and
* the gap at the end has the requested size. this method never shrinks the total storage. The
- * effect on this PyByteArray is that:
+ * effect on this <code>PyByteArray</code> is that:
*
* <pre>
* this.offset = f or 0
@@ -2518,7 +2521,7 @@
* </pre>
*
* where the regions of length <code>a</code> and <code>b=size-(a+d)</code> have been preserved
- * and the gap between them eliminated. The effect on this PyByteArray is that:
+ * and the gap between them eliminated. The effect on this <code>PyByteArray</code> is that:
*
* <pre>
* this.offset = f'
@@ -2526,8 +2529,8 @@
* </pre>
*
* The method does not implement the Python repertoire of slice indices but avoids indexing
- * outside the bytearray by silently adjusting a to be within it. Negative d is treated as 0 and
- * if d is too large, it is truncated to the array end.
+ * outside the <code>bytearray</code> by silently adjusting a to be within it. Negative d is
+ * treated as 0 and if d is too large, it is truncated to the array end.
*
* @param a index of hole in byte array
* @param d number to discard (will discard x[a,a+d-1])
@@ -2536,8 +2539,7 @@
private void storageDelete(int a, int d) {
// storageReplace specialised for delete (e=0)
- if (d == 0)
- {
+ if (d == 0) {
return; // Everything stays where it is.
}
@@ -2626,7 +2628,7 @@
* where the regions of length <code>a</code> and <code>b=size-(a+e)</code> have been preserved
* and the <code>e</code> intervening elements reduced to <code>e-d</code> elements, by removing
* exactly the elements with indices (relative to the start of valid data) <code>a+k*c</code>
- * for <code>k=0...d-1</code>. The effect on this PyByteArray is that:
+ * for <code>k=0...d-1</code>. The effect on this <code>PyByteArray</code> is that:
*
* <pre>
* this.offset = f'
@@ -2634,8 +2636,8 @@
* </pre>
*
* The method does not implement the Python repertoire of slice indices but avoids indexing
- * outside the bytearray by silently adjusting a to be within it. Negative d is treated as 0 and
- * if d is too large, it is truncated to the array end.
+ * outside the <code>bytearray</code> by silently adjusting a to be within it. Negative d is
+ * treated as 0 and if d is too large, it is truncated to the array end.
*
* @param a index of hole in byte array
* @param c (>0) step size between the locations of elements to delete
@@ -2647,4 +2649,3 @@
// XXX Change SequenceIndexDelegate to use (and PyList to implement) delslice()
}
}
-
--
Repository URL: http://hg.python.org/jython
More information about the Jython-checkins
mailing list