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.
Class Binary
Class ByteArray
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...)
Instance Properties
Static Methods
- wrap(bytes)
Class ByteString
Instance Methods
- byteAt(offset)
- concat(arg...)
- copy(start, end, target, targetStart)
- decodeToString(charset)
- get(offset)
- indexOf(sequence, start, stop)
- lastIndexOf(sequence, start, stop)
- slice(begin, end)
- split(delimiter, options)
- toArray()
- toByteArray()
- toByteString()
- toString()
Binary ()
Abstract base class for ByteArray and ByteString
ByteArray (contentOrLength, [charset])
Constructs a writable and growable byte array.
If the first argument to this constructor is a number, it specifies the initial length of the ByteArray in bytes.
Else, the argument defines the content of the ByteArray. If the argument is a String, the constructor requires a second argument containing the name of the String's encoding. If called without arguments, an empty ByteArray is returned.
Parameters
| Binary|Array|String|Number | contentOrLength | content or length of the ByteArray. |
| 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.
Returns
| Number |
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 |
| Object | 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 |
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 |
| Object | 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 |
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:
|
ByteArray.prototype. toArray ()
Returns an array containing the bytes as numbers.
ByteArray.prototype. toByteArray ()
ByteArray.prototype. toByteString ()
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 |
ByteString (content, charset)
Constructs an immutable byte string.
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.
Parameters
| Binary|Array|String | content | the content of the ByteString. |
| String | charset | the encoding name if the first argument is a String. |
ByteString.prototype. byteAt (offset)
Returns the byte at the given offset.
Parameters
| Number | offset |
Returns
| Number |
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]).
Parameters
| Number | offset |
Returns
| ByteString |
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:
|
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.
ByteString.prototype. toByteString ()
Returns this ByteString itself.
ByteString.prototype. toString ()
Returns a debug representation such as "[ByteSTring 10]" where 10 is the
length of this ByteString.
String
Not exported as constructor by this module.
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 |