Class BaseBytes

All Implemented Interfaces:
Serializable, Iterable<PyInteger>, Collection<PyInteger>, List<PyInteger>
Direct Known Subclasses:
PyByteArray

public abstract class BaseBytes extends PySequence implements List<PyInteger>
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. It is possible for a Java client to treat this class as a List<PyInteger>, obtaining equivalent functionality to the Python interface in a Java paradigm.

Subclasses must define (from PySequence):

  • getslice(int, int, int)
  • repeat(int)
each returning an appropriate concrete type. Mutable subclasses should override:
  • PySequence.pyset(int, PyObject)
  • PySequence.setslice(int, int, int, PyObject)
  • PySequence.del(int)
  • PySequence.delRange(int, int)
since the default implementations will otherwise throw an exception.

Many of the methods implemented here are inherited or thinly wrapped by PyByteArray, which offers them as Java API, or exposes them as Python methods. These prototype Python methods mostly accept a PyObject as argument, where you might have expected a byte[] or BaseBytes, in order to accommodate the full range of types accepted by the Python equivalent: usually, any PyObject that implements 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 BaseBytes when this broader scope is intended.

Where the methods return a BaseBytes, this is will normally be an instance of the class of the object on which the method was actually called. For example capitalize(), defined in BaseBytes to return a BaseBytes, actually returns a PyByteArray when applied to a bytearray. Or it may be that the method returns a PyList of instances of the target type, for example rpartition(PyObject). This is achieved by the sub-class defining getslice(int, int, int) and getResult(Builder) to return instances of its own type. See the documentation of the particular methods for more information.

See Also:
  • Constructor Details

    • BaseBytes

      public BaseBytes(PyType type)
      Constructs a zero-length BaseBytes of explicitly-specified sub-type.
      Parameters:
      type - explicit Jython type
    • BaseBytes

      public BaseBytes(PyType type, int size)
      Constructs a zero-filled array of defined size and type.
      Parameters:
      size - required
      type - explicit Jython type
    • BaseBytes

      public BaseBytes(PyType type, int[] value)
      Constructs a byte array of defined type by copying values from int[].
      Parameters:
      type - explicit Jython type
      value - source of values (and size)
  • Method Details

    • pyinsert

      public void pyinsert(int index, PyObject element)
      Insert the element (interpreted as a Python byte value) at the given index. The default implementation produces a Python TypeError, for the benefit of immutable types. Mutable types must override it.
      Parameters:
      index - to insert at
      element - to insert (by value)
      Throws:
      PyException - IndexError if the index is outside the array bounds
      PyException - ValueError if element<0 or element>255
      PyException - TypeError if the subclass is immutable
    • __len__

      public int __len__()
      Description copied from class: PyObject
      Equivalent to the standard Python __len__ method. Part of the mapping discipline.
      Overrides:
      __len__ in class PyObject
      Returns:
      the length of the object
    • asString

      public String asString()
      Present the bytes of a byte array, with no decoding, as a Java String. The bytes are treated as unsigned character codes, and copied to the to the characters of a String with no change in ordinal value. This could also be described as 'latin-1' or 'ISO-8859-1' decoding of the byte array to a String, since this character encoding is numerically equal to Unicode.
      Overrides:
      asString in class PyObject
      Returns:
      the byte array as a String
    • decode

      public PyObject decode()
      Decode the byte array to a Unicode string according to the default encoding. The returned PyObject should be a PyUnicode, since the default codec is well-behaved.
      Returns:
      object containing the decoded characters
    • decode

      public PyObject decode(String encoding)
      Decode the byte array to a Unicode string according to the specified encoding and default error policy. The returned PyObject will usually be a PyUnicode, but in practice it is whatever the decode method of the codec decides.
      Parameters:
      encoding - the name of the codec (uses default codec if null)
      Returns:
      object containing the decoded characters
    • decode

      public PyObject decode(String encoding, String errors)
      Decode the byte array to a Unicode string according to the specified encoding and error policy. The returned PyObject will usually be a PyUnicode, but in practice it is whatever the decode method of the codec decides.
      Parameters:
      encoding - the name of the codec (uses default codec if null)
      errors - the name of the error policy (uses 'strict' if null)
      Returns:
      object containing the decoded characters
    • __reduce__

      public PyObject __reduce__()
      Support for pickling byte arrays: reduce a byte array to the actual type, arguments for (re-)construction of the object, and the dictionary of any user-defined sub-class.
      Overrides:
      __reduce__ in class PyObject
      Returns:
      PyTuple that is first stage in pickling byte array
    • partition

      public PyTuple partition(PyObject sep)
      Implementation of Python partition(sep), returning a 3-tuple of byte arrays (of the same type as this). Split the string at the first occurrence of sep, and return a 3-tuple 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 the string itself, followed by two empty byte arrays.

      The elements of the PyTuple returned by this method are instances of the same actual type as this.

      Parameters:
      sep - the separator on which to partition this byte array
      Returns:
      a tuple of (head, separator, tail)
    • rpartition

      public PyTuple rpartition(PyObject sep)
      Implementation of Python rpartition(sep), returning a 3-tuple of byte arrays (of the same type as this). Split the string at the rightmost occurrence of sep, and return a 3-tuple 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.

      The elements of the PyTuple returned by this method are instances of the same actual type as this.

      Parameters:
      sep - the separator on which to partition this byte array
      Returns:
      a tuple of (head, separator, tail)
    • rsplit

      public PyList rsplit()
      Implementation of Python rsplit(), that returns a list of the words in the byte array, using whitespace as the delimiter. See rsplit(PyObject, int).

      The elements of the PyList returned by this method are instances of the same actual type as this.

      Returns:
      PyList of byte arrays that result from the split
    • rsplit

      public PyList rsplit(PyObject sep)
      Implementation of Python rsplit(sep), that returns a list of the words in the byte array, using sep as the delimiter. See rsplit(PyObject, int) for the semantics of the separator.

      The elements of the PyList returned by this method are instances of the same actual type as this.

      Parameters:
      sep - bytes, or object viewable as bytes, defining the separator
      Returns:
      PyList of byte arrays that result from the split
    • rsplit

      public PyList rsplit(PyObject sep, int maxsplit)
      Implementation of Python rsplit(sep, maxsplit), 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).

      The semantics of sep and maxcount are identical to those of split(sep, maxsplit) , 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 split if maxcount limits the number of splits. For example,

      • bytearray(b' 1 2 3 ').rsplit() returns [bytearray(b'1'), bytearray(b'2'), bytearray(b'3')], and
      • bytearray(b' 1 2 3 ').rsplit(None, 1) returns [bytearray(b' 1 2'), bytearray(b'3')].

      The elements of the PyList returned by this method are instances of the same actual type as this.

      Parameters:
      sep - bytes, or object viewable as bytes, defining the separator
      maxsplit - maximum number of splits
      Returns:
      PyList of byte arrays that result from the split
    • split

      public PyList split()
      Implementation of Python split(), that returns a list of the words in the byte array, using whitespace as the delimiter. See split(PyObject, int).

      The elements of the PyList returned by this method are instances of the same actual type as this.

      Returns:
      PyList of byte arrays that result from the split
    • split

      public PyList split(PyObject sep)
      Implementation of Python split(sep), that returns a list of the words in the byte array, using sep as the delimiter. See split(PyObject, int) for the semantics of the separator.

      The elements of the PyList returned by this method are instances of the same actual type as this.

      Parameters:
      sep - bytes, or object viewable as bytes, defining the separator
      Returns:
      PyList of byte arrays that result from the split
    • split

      public PyList split(PyObject sep, int maxsplit)
      Implementation of Python split(sep, maxsplit), 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).

      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 [''].

      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,

      • bytearray(b' 1 2 3 ').split() returns [bytearray(b'1'), bytearray(b'2'), bytearray(b'3')], and
      • bytearray(b' 1 2 3 ').split(None, 1) returns [bytearray(b'1'), bytearray(b'2 3 ')].

      The elements of the PyList returned by this method are instances of the same actual type as this.

      Parameters:
      sep - bytes, or object viewable as bytes, defining the separator
      maxsplit - maximum number of splits
      Returns:
      PyList of byte arrays that result from the split
    • splitlines

      public PyList splitlines()
      Implementation of Python splitlines(), returning a list of the lines in the byte array, breaking at line boundaries. Line breaks are not included in the resulting segments.

      The elements of the PyList returned by this method are instances of the same actual type as this.

      Returns:
      List of segments
    • splitlines

      public PyList splitlines(boolean keepends)
      Implementation of Python splitlines(keepends), returning a list of the lines in the string, breaking at line boundaries. Line breaks are not included in the resulting list unless keepends is true.

      The elements of the PyList returned by this method are instances of the same actual type as this.

      Parameters:
      keepends - if true, include the end of line bytes(s)
      Returns:
      PyList of segments
    • isalnum

      public boolean isalnum()
      Java API equivalent of Python isalnum(). This method treats the bytes as US-ASCII code points.
      Returns:
      true if all bytes in the array are code points for alphanumerics and there is at least one byte, false otherwise.
    • isalpha

      public boolean isalpha()
      Java API equivalent of Python isalpha(). This method treats the bytes as US-ASCII code points.
      Returns:
      true if all bytes in the array are alphabetic and there is at least one byte, false otherwise
    • isdigit

      public boolean isdigit()
      Java API equivalent of Python isdigit(). This method treats the bytes as US-ASCII code points.
      Returns:
      true if all bytes in the array are code points for digits and there is at least one byte, false otherwise.
    • islower

      public boolean islower()
      Java API equivalent of Python islower(). This method treats the bytes as US-ASCII code points.
      Returns:
      true if all cased bytes in the array are code points for lowercase characters and there is at least one cased byte, false otherwise.
    • isspace

      public boolean isspace()
      Java API equivalent of Python isspace(). This method treats the bytes as US-ASCII code points.
      Returns:
      true if all the bytes in the array are code points for whitespace characters and there is at least one byte, false otherwise.
    • istitle

      public boolean istitle()
      Java API equivalent of Python istitle(). This method treats the bytes as US-ASCII code points.
      Returns:
      true if the string is a titlecased string and there is at least one cased byte, for example uppercase characters may only follow uncased bytes and lowercase characters only cased ones. Return false otherwise.
    • isupper

      public boolean isupper()
      Java API equivalent of Python isupper(). This method treats the bytes as US-ASCII code points.
      Returns:
      true if all cased bytes in the array are code points for uppercase characters and there is at least one cased byte, false otherwise.
    • capitalize

      public BaseBytes capitalize()
      Java API equivalent of Python capitalize(). This method treats the bytes as US-ASCII code points. The BaseBytes returned by this method has the same actual type as this/self.
      Returns:
      a copy of the array with its first character capitalized and the rest lowercased.
    • lower

      public BaseBytes lower()
      Java API equivalent of Python lower(). This method treats the bytes as US-ASCII code points. The BaseBytes returned by this method has the same actual type as this/self.
      Returns:
      a copy of the array with all the cased characters converted to lowercase.
    • swapcase

      public BaseBytes swapcase()
      Java API equivalent of Python swapcase(). This method treats the bytes as US-ASCII code points. The BaseBytes returned by this method has the same actual type as this/self.
      Returns:
      a copy of the array with uppercase characters converted to lowercase and vice versa.
    • title

      public BaseBytes title()
      Java API equivalent of Python title(). 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. The BaseBytes returned by this method has the same actual type as this/self.
      Returns:
      a titlecased version of the array where words start with an uppercase character and the remaining characters are lowercase.
    • upper

      public BaseBytes upper()
      Java API equivalent of Python upper(). Note that x.upper().isupper() might be false if the array contains uncased characters. The BaseBytes returned by this method has the same actual type as this/self.
      Returns:
      a copy of the array with all the cased characters converted to uppercase.
    • intAt

      public int intAt(int index) throws PyException
      Return the Python byte (in range 0 to 255 inclusive) at the given index.
      Parameters:
      index - of value in byte array
      Returns:
      the integer value at the index
      Throws:
      PyException - IndexError if the index is outside the array bounds
    • size

      public int size()
      Number of bytes in bytearray (or bytes) object.
      Specified by:
      size in interface Collection<PyInteger>
      Specified by:
      size in interface List<PyInteger>
      Returns:
      Number of bytes in byte array.
      See Also:
    • isEmpty

      public boolean isEmpty()
      Specified by:
      isEmpty in interface Collection<PyInteger>
      Specified by:
      isEmpty in interface List<PyInteger>
    • contains

      public boolean contains(Object o)
      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)).
      Specified by:
      contains in interface Collection<PyInteger>
      Specified by:
      contains in interface List<PyInteger>
    • iterator

      public Iterator<PyInteger> iterator()
      Specified by:
      iterator in interface Collection<PyInteger>
      Specified by:
      iterator in interface Iterable<PyInteger>
      Specified by:
      iterator in interface List<PyInteger>
    • toArray

      public Object[] toArray()
      Specified by:
      toArray in interface Collection<PyInteger>
      Specified by:
      toArray in interface List<PyInteger>
    • toArray

      public <T> T[] toArray(T[] a)
      Specified by:
      toArray in interface Collection<PyInteger>
      Specified by:
      toArray in interface List<PyInteger>
    • add

      public boolean add(PyInteger o)
      Specified by:
      add in interface Collection<PyInteger>
      Specified by:
      add in interface List<PyInteger>
    • remove

      public boolean remove(Object o)
      Specified by:
      remove in interface Collection<PyInteger>
      Specified by:
      remove in interface List<PyInteger>
    • containsAll

      public boolean containsAll(Collection<?> c)
      Specified by:
      containsAll in interface Collection<PyInteger>
      Specified by:
      containsAll in interface List<PyInteger>
    • addAll

      public boolean addAll(Collection<? extends PyInteger> c)
      Specified by:
      addAll in interface Collection<PyInteger>
      Specified by:
      addAll in interface List<PyInteger>
    • addAll

      public boolean addAll(int index, Collection<? extends PyInteger> c)
      Specified by:
      addAll in interface List<PyInteger>
    • removeAll

      public boolean removeAll(Collection<?> c)
      Specified by:
      removeAll in interface Collection<PyInteger>
      Specified by:
      removeAll in interface List<PyInteger>
    • retainAll

      public boolean retainAll(Collection<?> c)
      Specified by:
      retainAll in interface Collection<PyInteger>
      Specified by:
      retainAll in interface List<PyInteger>
    • clear

      public void clear()
      Specified by:
      clear in interface Collection<PyInteger>
      Specified by:
      clear in interface List<PyInteger>
    • equals

      public boolean equals(Object other)
      Test for the equality of (the value of) this byte array to the object other. In the case where other is a PyObject, the comparison used is the standard Python == operation through PyObject. When other is not a PyObject, this object acts as a List<PyInteger>.
      Specified by:
      equals in interface Collection<PyInteger>
      Specified by:
      equals in interface List<PyInteger>
      Overrides:
      equals in class PyObject
      Parameters:
      other - object to compare this byte array to
      Returns:
      true if and only if this byte array is equal (in value) to other
      See Also:
    • hashCode

      public int hashCode()
      Specified by:
      hashCode in interface Collection<PyInteger>
      Specified by:
      hashCode in interface List<PyInteger>
      Overrides:
      hashCode in class PyObject
    • get

      public PyInteger get(int index)
      Specified by:
      get in interface List<PyInteger>
    • set

      public PyInteger set(int index, PyInteger element)
      Specified by:
      set in interface List<PyInteger>
    • add

      public void add(int index, PyInteger element)
      Specified by:
      add in interface List<PyInteger>
    • remove

      public PyInteger remove(int index)
      Specified by:
      remove in interface List<PyInteger>
    • indexOf

      public int indexOf(Object o)
      Specified by:
      indexOf in interface List<PyInteger>
    • lastIndexOf

      public int lastIndexOf(Object o)
      Specified by:
      lastIndexOf in interface List<PyInteger>
    • listIterator

      public ListIterator<PyInteger> listIterator()
      Specified by:
      listIterator in interface List<PyInteger>
    • listIterator

      public ListIterator<PyInteger> listIterator(int index)
      Specified by:
      listIterator in interface List<PyInteger>
    • subList

      public List<PyInteger> subList(int fromIndex, int toIndex)
      Specified by:
      subList in interface List<PyInteger>