在处理网络套接字或二进制文件时,需要读取和写入字节流。 JavaScript 本身并不提供二进制数据的本地表示,所以这个模块提供了两个类来解决这个缺点。 实施遵循 CommonJS Binary/B 提案。
ByteArray
实现了可修改和可调整大小的字节缓冲区。
ByteString
实现一个不可变的字节序列。
两个类共享一个通用的基类 Binary
。 基类不能被实例化。 它仅用于确认 Binary
的 ByteString
和 ByteArray
实例。
当传递给需要 byte[]
的 Java 方法时,这些类的实例会自动解包。
// raw network streams only accept Binary as input
var stream = socket.getStream();
stream.write(new ByteArray([0xFA, 0xF0, 0x10, 0x58, 0xFF]));
// network protocols like HTTP/1.1 require ASCII
const CRLF = new ByteString("\r\n", "ASCII");
const EMPTY_LINE = new ByteString("\r\n\r\n", "ASCII");
// saves a java.security.Key to a file;
// the method getEncoded() returns a Java byte[]
fs.write("id_dsa.pub", ByteArray.wrap(publicKey.getEncoded()));
// Generates a salt for hashing
var random = java.security.SecureRandom.getInstance("SHA1PRNG");
var salt = new ByteArray(8);
random.nextBytes(salt); // fills up salt with random bytes
ByteArray 和 ByteString 的抽象基类。二进制类型仅用于确认 Binary 的 ByteString 和 ByteArray 实例。
构造一个可写和可生长的字节数组。
如果此构造函数的第一个参数是一个数字,它将指定 ByteArray 的初始长度(以字节为单位)。否则,参数定义了 ByteArray 的内容。如果参数是一个 String,则构造函数需要第二个参数,其中包含 String 的编码名称。如果没有参数调用,则返回一个空的 ByteArray。
Binary|Array|String|Number | contentOrLength | content or length of the ByteArray. |
String | [charset] | the encoding name if the first argument is a String. |
以 ByteArray 的形式返回给定偏移量处的字节。
var ba = new ByteArray([0,1,2,4,8]);
ba.byteAt(0); // --> [ByteArray 1]
Number | offset |
ByteArray |
以 ByteArray 的形式返回给定偏移量处的字节。
var ba = new ByteArray([0,1,2,4,8]);
ba.charAt(0); // --> [ByteArray 1]
Number | offset |
ByteArray |
在给定的偏移量处返回 charcode。
var ba = new ByteArray([0,1,2,4,8]);
ba.charCodeAt(0); // --> 0
Number | offset |
Number |
返回由与给定的 ByteString,ByteArray 和 Array 值连接的自身组成的 ByteArray。
Binary...|Array... | args... | one or more elements to concatenate |
ByteArray | a new ByteArray |
将从此对象开始和停止之间的一系列字节复制到给定目标偏移量处的另一个 ByteArray。
Number | start | |
Number | end | |
ByteArray | target | |
Number | targetOffset |
使用给定的编码返回解码为字符串的 ByteArray
var ba = new ByteArray([240, 159, 152, 130]);
console.log(ba.decodeToString("UTF-8")); // prints 😂
String | encoding | the name of the encoding to use |
测试数组中的所有元素是否都通过了由提供的函数实现的测试。
var ba = new ByteArray([0,1,2,3,4,5,6,7,8]);
ba.every(function(byte) { return byte > 5; }); // --> false
ba.every(function(byte) { return byte < 10; }); // --> true
Function | callback | the callback function |
Object | thisObj | optional this-object for callback |
Boolean | true if every invocation of callback returns true |
返回包含此回调函数返回 true 的此 ByteArray 元素的 ByteArray。
var ba = "hello world".toByteArray();
var bf = ba.filter(function(byte) { return byte > 110 });
bf.decodeToString(); // returns "owor"
Function | callback | the filter function |
Object | thisObj | optional this-object for callback |
ByteArray | a new ByteArray |
为 ByteArray 中的每个元素应用一个函数。
var ba = "hello world".toByteArray();
// prints 104, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100
ba.forEach(function(byte) { console.log(byte) });
Function | fn | the function to call for each element |
Object | thisObj | optional this-object for callback |
以整数形式返回给定偏移量处的字节。 get(offset) 与括号 [offset] 的索引类似。
var ba = new ByteArray([0,255]);
print(ba[0]); // prints 0
Number | offset |
Number |
返回序列第一次出现的索引(一个 Number 或一个 ByteString 或任意长度的 ByteArray),如果没有找到,则返回 -1。如果指定了开始和 / 或停止,则只搜索索引开始和停止之间的元素。
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 |
Number | the index of the first occurrence of sequence, or -1 |
返回序列的最后一次出现的索引(一个 Number 或一个 ByteString 或任何长度的 ByteArray),如果没有找到,则返回 -1 。如果指定了开始和 / 或停止,则只搜索索引开始和停止之间的元素。
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 |
Number | the index of the last occurrence of sequence, or -1 |
以字节为单位的长度。该属性是可写的。将其设置为高于当前值的值将使用 0 填充新插槽,将其设置为较低的值会截断字节数组。
返回一个新的 ByteArray,其内容是使用原始 ByteArray 的每个元素调用提供的函数的结果。
var ba1 = new ByteArray([0,1,2,3,4,5,6,7,8]);
var ba2 = ba1.map(function(byte) { return 2 * byte; });
console.log(ba2.toArray()); // prints [0, 2, 4, 6, 8, 10, 12, 14, 16]
Function | callback | the callback |
Object | thisObj | optional this-object for callback |
ByteArray | a new ByteArray |
从数组中删除最后一个元素并返回该元素。
var ba = new ByteArray([0,1,2,4,8]);
ba.pop() === 8; // --> true
Number |
追加给定的元素并返回数组的新长度。
var ba = new ByteArray([0,1,2,4,8]);
ba.push(16);
console.log(ba.toArray()); // [0, 1, 2, 4, 8, 16]
Number... | num... | one or more numbers to append |
Number | the new length of the ByteArray |
将此函数应用于此 ByteArray 中的每个元素,从左到右将其内容减少为单个值。
var ba = new ByteArray([0,1,2,3,4,5,6,7,8]);
ba.reduce(function(prev, curr) { return prev + curr; }); // --> 36
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 |
the return value of the last callback invocation |
将一个函数应用于此ByteArray中从最后一个元素开始的每个元素,以将其内容减少为单个值。
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 |
the return value of the last callback invocation |
颠倒 ByteArray 的内容。
var ba = new ByteArray([0,1,2,3,4,5,6,7,8]);
ba.reverse();
print(ba[0] == 8); // --> true
ByteArray | this ByteArray with its elements reversed |
设置给定偏移量处的字节。 set(offset,value) 与括号 [offset] = value 的索引类似。
var ba = new ByteArray([0,255]);
ba[0] = 64;
print(ba[0]); // prints 64
Number | offset | |
Number | value |
从 ByteArray 中移除第一个元素并返回该元素。此方法更改 ByteArray 的长度。
var ba = new ByteArray([0,1,2,4,8]);
ba.shift();
console.log(ba.toArray()); // [1, 2, 4, 8]
Number | the removed first element |
返回包含此 ByteArray 一部分的新 ByteArray。
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. |
ByteArray | a new ByteArray |
测试数组中的某个元素是否通过了由提供的函数实现的测试。
var ba = new ByteArray([0,1,2,3,4,5,6,7,8]);
ba.some(function(byte) { return byte > 10; }); // --> false
ba.some(function(byte) { return byte < 10; }); // --> true
Function | callback | the callback function |
Object | thisObj | optional this-object for callback |
Boolean | true if at least one invocation of callback returns true |
在原地排列 ByteArray 的内容。
var ba = "hello world".toByteArray();
ba.sort();
ba.decodeToString() // --> "dehllloorw"
Function | comparator | the function to compare entries |
ByteArray | this ByteArray with its elements sorted |
更改 ByteArray 的内容,在删除旧元素的同时添加新元素。
var ba = new ByteArray([0,1,2,4,8]);
ba.splice(2,2);
console.log(ba.toArray()); // [0, 1, 8]
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 |
在分隔符处分割,可以通过 Number,ByteString,ByteArray 或先前的 Array(包含多个分隔符,即“在任何这些分隔符处分割”)来分隔。分隔符可以具有任意大小。
Number|Binary | delimiter | one or more delimiter items |
Object | options | optional object parameter with the following optional properties:
|
将包含字节的数组作为数字返回。
返回 ByteArray 的字符串表示形式。
var ba = new ByteArray([0,1,2,4,8]);
console.log(ba.toString()); // prints '[ByteArray 5]'
将一个或多个元素添加到 ByteArray 的开头并返回其新长度。
var ba = new ByteArray([0,1,2,4,8]);
ba.unshift(-8, -4, -2, -1);
console.log(ba.toArray()); // [248, 252, 254, 255, 0, 1, 2, 4, 8]
Number... | num... | one or more numbers to append |
Number | the new length of the ByteArray |
从 ByteArray 解开基础 Java byte []。它可以传递给需要一个字节数组的Java方法。
byte[] | a native Java byte array |
为 ByteArray 构造函数创建 ByteArray 包装器,而不创建新副本。对 ByteArray 实例所做的任何更改都将应用于原始字节数组。
// writes a java.security.Key byte[] to a file;
fs.write("id_dsa.pub", ByteArray.wrap(publicKey.getEncoded()));
Binary | bytes | a Java byte array or Binary instance |
ByteArray | a ByteArray wrapping the argument |
构造一个不可变的字节字符串。
如果第一个参数是一个字符串,则构造函数需要第二个参数包含该字符串的编码名称。如果没有参数调用,则返回一个空的 ByteString。
Binary|Array|String | content | the content of the ByteString. |
String | charset | the encoding name if the first argument is a String. |
以 ByteString 的形式返回给定偏移量处的字节。
Number | offset |
ByteString |
以 ByteString 的形式返回给定偏移量处的字节。
Number | offset |
ByteString |
在给定的偏移量处返回 charcode。
Number | offset |
Number |
返回由与给定的 ByteString,ByteArray 和 Array 值连接的自身组成的 ByteString。
Binary...|Array... | args... | one or more elements to concatenate |
ByteString | a new ByteString |
将从此 ByteString 开始和停止之间的一系列字节复制到给定 targetStart 偏移量处的目标 ByteArray。
Number | start | |
Number | end | |
ByteArray | target | |
Number | targetStart |
将此ByteString作为字符串返回,并使用给定的字符集进行解码。
String | charset | the name of the string encoding |
以 ByteString 的形式返回给定偏移量处的字节。 get(offset) 与括号 [offset] 的索引类似。
Number | offset |
ByteString |
返回序列第一次出现的索引(一个 Number 或一个 ByteString 或任意长度的 ByteArray),如果没有找到,则返回 -1。如果指定了开始和 / 或停止,则只搜索索引开始和停止之间的元素。
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 |
Number | the index of the first occurrence of sequence, or -1 |
返回序列的最后一次出现的索引(一个 Number 或一个 ByteString 或任何长度的 ByteArray),如果没有找到,则返回 -1。如果指定了开始和 / 或停止,则只搜索索引开始和停止之间的元素。
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 |
Number | the index of the last occurrence of sequence, or -1 |
以字节为单位的长度。此属性是只读的。将它设置为一个值默默地失败。
返回包含此ByteString一部分的新ByteString。
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. |
ByteString | a new ByteString |
在分隔符处分割,可以通过 Number,ByteString,ByteArray 或先前的 Array(包含多个分隔符,即“在任何这些分隔符处分割”)来分隔。分隔符可以具有任意大小。
Number|Binary | delimiter | one or more delimiter items |
Object | options | optional object parameter with the following optional properties:
|
将包含字节的数组作为数字返回。
返回这个 ByteString 本身。
返回一个调试表示,如 “[ByteSTring 10]”,其中 10 是此 ByteString 的长度。
从 ByteString 解开基础 Java byte []。它可以传递给需要一个字节数组的 Java 方法。
byte[] | a native Java byte array |
为 ByteString 构造函数创建 ByteString 包装器,而不创建新副本。
Binary | bytes | a Java byte array or Binary instance |
ByteString | a ByteString wrapping the argument |
不通过此模块导出为构造函数。
使用指定的编码将字符串转换为可变的 ByteArray。
var ba = "hello world".toByteArray();
String | charset | the name of the string encoding. Defaults to 'UTF-8' |
ByteArray | a ByteArray representing the string |
使用指定的编码将字符串转换为不可变的 ByteString。
var bs = "hello world".toByteString();
String | charset | the name of the string encoding. Defaults to 'UTF-8' |
ByteString | a ByteString representing the string |