Class BaseBytes

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Iterable<PyInteger>, java.util.Collection<PyInteger>, java.util.List<PyInteger>
    Direct Known Subclasses:
    PyByteArray

    public abstract class BaseBytes
    extends PySequence
    implements java.util.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):

    each returning an appropriate concrete type. Mutable subclasses should override: 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 getBuilder(int) to return instances of its own type. See the documentation of particular methods for more information.

    See Also:
    Serialized Form
    • Constructor Detail

      • 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 Detail

      • 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 java.lang.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​(java.lang.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​(java.lang.String encoding,
                               java.lang.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 java.util.Collection<PyInteger>
        Specified by:
        size in interface java.util.List<PyInteger>
        Returns:
        Number of bytes in byte array.
        See Also:
        List.size()
      • isEmpty

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

        public boolean contains​(java.lang.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 java.util.Collection<PyInteger>
        Specified by:
        contains in interface java.util.List<PyInteger>
      • iterator

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

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

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

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

        public boolean remove​(java.lang.Object o)
        Specified by:
        remove in interface java.util.Collection<PyInteger>
        Specified by:
        remove in interface java.util.List<PyInteger>
      • containsAll

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

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

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

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

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

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

        public boolean equals​(java.lang.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 java.util.Collection<PyInteger>
        Specified by:
        equals in interface java.util.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:
        List.equals(java.lang.Object)
      • hashCode

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

        public PyInteger get​(int index)
        Specified by:
        get in interface java.util.List<PyInteger>
      • add

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

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

        public int indexOf​(java.lang.Object o)
        Specified by:
        indexOf in interface java.util.List<PyInteger>
      • lastIndexOf

        public int lastIndexOf​(java.lang.Object o)
        Specified by:
        lastIndexOf in interface java.util.List<PyInteger>
      • listIterator

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

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

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