Module binary
This module provides implementations of the Binary,
ByteArray, and ByteString classes as defined in the CommonJS Binary/B
proposal.
The JavaScript Binary class serves as common base class for ByteArray and
ByteString and can't be instantiated. ByteArray implements a modifiable and
resizable byte buffer, while ByteString implements an immutable byte
sequence. The ByteArray and ByteString constructors can take several
arguments. Have a look at the proposal for details.
When passed to a Java method that expects a byte array, instances of
these class are automatically unwrapped. Use the {@link #unwrap()} method to
explicitly get the wrapped Java byte array.
Instance Methods
-
concat(arg...)
-
copy(start, end, target, targetOffset)
-
decodeToString(encoding)
-
every(callback, thisObj)
-
filter(callback, thisObj)
-
forEach(fn, thisObj)
-
indexOf(sequence, start, stop)
-
lastIndexOf(sequence, start, stop)
-
map(callback, thisObj)
-
pop()
-
push(num...)
-
reduce(callback, initialValue)
-
reduceRight(callback, initialValue)
-
reverse()
-
shift()
-
slice(begin, end)
-
some(callback, thisObj)
-
sort(comparator)
-
splice(index, howMany, elements...)
-
split(delimiter, options)
-
toArray()
-
toByteArray()
-
toByteString()
-
toString()
-
unshift(num...)
Abstract base class for ByteArray and ByteString
ByteArray
(content, charset)
Constructs a writable and growable byte array.
Parameters
| Binary|Array|String |
content |
the content of the ByteArray. If the
first argument is a String, the constructor requires a second
argument containing the name of the String's encoding. If called
without arguments, an empty ByteString is returned. |
| String |
charset |
the encoding name if the first argument is a String. |
ByteArray.prototype.concat
(arg...)
Returns a ByteArray composed of itself concatenated with the given
ByteString, ByteArray, and Array values.
Parameters
| Binary|Array |
arg... |
one or more elements to concatenate |
Returns
| ByteArray |
a new ByteArray |
ByteArray.prototype.copy
(start, end, target, targetOffset)
Copy a range of bytes between start and stop from this object to another
ByteArray at the given target offset.
Parameters
| Number |
start |
|
| Number |
end |
|
| ByteArray |
target |
|
| Number |
targetOffset |
|
ByteArray.prototype.decodeToString
(encoding)
Returns the ByteArray decoded to a String using the given encoding
Parameters
| String |
encoding |
the name of the encoding to use |
ByteArray.prototype.every
(callback, thisObj)
Tests whether all elements in the array pass the test implemented by the
provided function.
Parameters
| Function |
callback |
the callback function |
| Object |
thisObj |
optional this-object for callback |
Returns
| Boolean |
true if every invocation of callback returns true |
ByteArray.prototype.filter
(callback, thisObj)
Return a ByteArray containing the elements of this ByteArray for which
the callback function returns true.
Parameters
| Function |
callback |
the filter function |
| Object |
thisObj |
optional this-object for callback |
Returns
| ByteArray |
a new ByteArray |
ByteArray.prototype.forEach
(fn, thisObj)
Apply a function for each element in the ByteArray.
Parameters
| Function |
fn |
the function to call for each element |
| Object |
thisObj |
optional this-object for callback |
ByteArray.prototype.indexOf
(sequence, start, stop)
Returns the index of the first occurrence of sequence (a Number or a
ByteString or ByteArray of any length) or -1 if none was found. If start
and/or stop are specified, only elements between the indexes start and stop
are searched.
Parameters
| Number|Binary |
sequence |
the number or binary to look for |
| Number |
start |
optional index position at which to start searching |
| Number |
stop |
optional index position at which to stop searching |
Returns
| Number |
the index of the first occurrence of sequence, or -1 |
ByteArray.prototype.lastIndexOf
(sequence, start, stop)
Returns the index of the last occurrence of sequence (a Number or a
ByteString or ByteArray of any length) or -1 if none was found. If start
and/or stop are specified, only elements between the indexes start and stop
are searched.
Parameters
| Number|Binary |
sequence |
the number or binary to look for |
| Number |
start |
optional index position at which to start searching |
| Number |
stop |
optional index position at which to stop searching |
Returns
| Number |
the index of the last occurrence of sequence, or -1 |
ByteArray.prototype.length
The length in bytes. This property is writable. Setting it to a value higher
than the current value fills the new slots with 0, setting it to a lower
value truncates the byte array.
ByteArray.prototype.map
(callback, thisObj)
Returns a new ByteArray whose content is the result of calling the provided
function with every element of the original ByteArray
Parameters
| Function |
callback |
the callback |
| Object |
thisObj |
optional this-object for callback |
Returns
| ByteArray |
a new ByteArray |
ByteArray.prototype.pop
()
Removes the last element from an array and returns that element.
ByteArray.prototype.push
(num...)
Appends the given elements and returns the new length of the array.
Parameters
| Number |
num... |
one or more numbers to append |
Returns
| Number |
the new length of the ByteArray |
ByteArray.prototype.reduce
(callback, initialValue)
Apply a function to each element in this ByteArray as to reduce its content
to a single value.
Parameters
| Function |
callback |
the function to call with each element of the
ByteArray |
|
initialValue |
optional argument to be used as the first argument to
the first call to the callback |
Returns
|
the return value of the last callback invocation |
See
ByteArray.prototype.reduceRight
(callback, initialValue)
Apply a function to each element in this ByteArray starting at the last
element as to reduce its content to a single value.
Parameters
| Function |
callback |
the function to call with each element of the
ByteArray |
|
initialValue |
optional argument to be used as the first argument to
the first call to the callback |
Returns
|
the return value of the last callback invocation |
See
ByteArray.prototype.reverse
()
Reverses the content of the ByteArray in-place
Returns
| ByteArray |
this ByteArray with its elements reversed |
ByteArray.prototype.shift
()
Removes the first element from the ByteArray and returns that element.
This method changes the length of the ByteArray
Returns
| Number |
the removed first element |
ByteArray.prototype.slice
(begin, end)
Returns a new ByteArray containing a portion of this ByteArray.
Parameters
| Number |
begin |
Zero-based index at which to begin extraction.
As a negative index, begin indicates an offset from the end of the
sequence. |
| Number |
end |
Zero-based index at which to end extraction.
slice extracts up to but not including end.
As a negative index, end indicates an offset from the end of the
sequence.
If end is omitted, slice extracts to the end of the sequence. |
Returns
| ByteArray |
a new ByteArray |
ByteArray.prototype.some
(callback, thisObj)
Tests whether some element in the array passes the test implemented by the
provided function.
Parameters
| Function |
callback |
the callback function |
| Object |
thisObj |
optional this-object for callback |
Returns
| Boolean |
true if at least one invocation of callback returns true |
ByteArray.prototype.sort
(comparator)
Sorts the content of the ByteArray in-place.
Parameters
| Function |
comparator |
the function to compare entries |
Returns
| ByteArray |
this ByteArray with its elements sorted |
ByteArray.prototype.splice
(index, howMany, elements...)
Changes the content of the ByteArray, adding new elements while removing old
elements.
Parameters
| Number |
index |
the index at which to start changing the ByteArray |
| Number |
howMany |
The number of elements to remove at the given
position |
| Number |
elements... |
the new elements to add at the given position |
ByteArray.prototype.split
(delimiter, options)
Split at delimiter, which can by a Number, a ByteString, a ByteArray or an
Array of the prior (containing multiple delimiters, i.e., "split at any of
these delimiters"). Delimiters can have arbitrary size.
Parameters
| Number|Binary |
delimiter |
one or more delimiter items |
| Object |
options |
optional object parameter with the following
optional properties:
- count - Maximum number of elements (ignoring delimiters) to
return. The last returned element may contain delimiters.
- includeDelimiter - Whether the delimiter should be included in
the result.
|
ByteArray.prototype.toArray
()
Returns an array containing the bytes as numbers.
ByteArray.prototype.toString
()
Returns a String representation of the ByteArray.
ByteArray.prototype.unshift
(num...)
Adds one or more elements to the beginning of the ByteArray and returns its
new length.
Parameters
| Number |
num... |
one or more numbers to append |
Returns
| Number |
the new length of the ByteArray |
ByteArray.wrap
(bytes)
Create a ByteArray wrapper for a Java byte array without creating a new copy
as the ByteArray constructor does. Any changes made on the ByteArray
instance will be applied to the original byte array.
Parameters
| Binary |
bytes |
a Java byte array or Binary instance |
Returns
| ByteArray |
a ByteArray wrapping the argument |
Constructs an immutable byte string.
Parameters
| Binary|Array|String |
content |
the content of the ByteString. If the
first argument is a String, the constructor requires a second
argument containing the name of the String's encoding. If called
without arguments, an empty ByteString is returned. |
| String |
charset |
the encoding name if the first argument is a String. |
ByteString.prototype.byteAt
(offset)
Returns the byte at the given offset.
ByteString.prototype.concat
(arg...)
Returns a ByteString composed of itself concatenated with the given
ByteString, ByteArray, and Array values.
Parameters
| Binary|Array |
arg... |
one or more elements to concatenate |
Returns
| ByteString |
a new ByteString |
ByteString.prototype.copy
(start, end, target, targetStart)
Copy a range of bytes between start and stop from this ByteString to a
target ByteArray at the given targetStart offset.
Parameters
| Number |
start |
|
| Number |
end |
|
| ByteArray |
target |
|
| Number |
targetStart |
|
ByteString.prototype.decodeToString
(charset)
Returns this ByteString as string, decoded using the given charset.
Parameters
| String |
charset |
the name of the string encoding |
ByteString.prototype.get
(offset)
Returns the byte at the given offset as a ByteString. get(offset) is
analogous to indexing with brackets ([offset]).
ByteString.prototype.indexOf
(sequence, start, stop)
Returns the index of the first occurrence of sequence (a Number or a
ByteString or ByteArray of any length), or -1 if none was found. If start
and/or stop are specified, only elements between the indexes start and stop
are searched.
Parameters
| Number|Binary |
sequence |
the number or binary to look for |
| Number |
start |
optional index position at which to start searching |
| Number |
stop |
optional index position at which to stop searching |
Returns
| Number |
the index of the first occurrence of sequence, or -1 |
ByteString.prototype.lastIndexOf
(sequence, start, stop)
Returns the index of the last occurrence of sequence (a Number or a
ByteString or ByteArray of any length) or -1 if none was found. If start
and/or stop are specified, only elements between the indexes start and stop
are searched.
Parameters
| Number|Binary |
sequence |
the number or binary to look for |
| Number |
start |
optional index position at which to start searching |
| Number |
stop |
optional index position at which to stop searching |
Returns
| Number |
the index of the last occurrence of sequence, or -1 |
ByteString.prototype.slice
(begin, end)
Returns a new ByteString containing a portion of this ByteString.
Parameters
| Number |
begin |
Zero-based index at which to begin extraction.
As a negative index, begin indicates an offset from the end of the
sequence. |
| Number |
end |
Zero-based index at which to end extraction. slice
extracts up to but not including end. As a negative index, end
indicates an offset from the end of the sequence. If end is omitted,
slice extracts to the end of the sequence. |
Returns
| ByteString |
a new ByteString |
ByteString.prototype.split
(delimiter, options)
Split at delimiter, which can by a Number, a ByteString, a ByteArray or an
Array of the prior (containing multiple delimiters, i.e., "split at any of
these delimiters"). Delimiters can have arbitrary size.
Parameters
| Number|Binary |
delimiter |
one or more delimiter items |
| Object |
options |
optional object parameter with the following
optional properties:
- count - Maximum number of elements (ignoring delimiters) to
return. The last returned element may contain delimiters.
- includeDelimiter - Whether the delimiter should be included in
the result.
|
ByteString.prototype.toArray
()
Returns an array containing the bytes as numbers.
ByteString.prototype.toByteArray
()
Returns a byte for byte copy of this immutable ByteString as a mutable
ByteArray.
Returns this ByteString itself.
ByteString.prototype.toString
()
Returns a debug representation such as "[ByteSTring 10]" where 10 is the
length of this ByteString.
String.prototype.toByteArray
(charset)
Converts the String to a mutable ByteArray using the specified encoding.
Parameters
| String |
charset |
the name of the string encoding. Defaults to 'UTF-8' |
Returns
|
a ByteArray representing the string |
String.prototype.toByteString
(charset)
Converts the String to an immutable ByteString using the specified encoding.
Parameters
| String |
charset |
the name of the string encoding. Defaults to 'UTF-8' |
Returns
|
a ByteArray representing the string |
