脚本开发

JS API 手册 REST API 手册 (仅专业版支持) RingoJS
RingoJS 1.2.1

模块 binary

在处理网络套接字或二进制文件时，需要读取和写入字节流。 JavaScript 本身并不提供二进制数据的本地表示，所以这个模块提供了两个类来解决这个缺点。 实施遵循 CommonJS Binary/B 提案。

ByteArray 实现了可修改和可调整大小的字节缓冲区。

ByteString 实现一个不可变的字节序列。

两个类共享一个通用的基类 Binary。 基类不能被实例化。 它仅用于确认 Binary 的 ByteString 和 ByteArray 实例。

当传递给需要 byte[] 的 Java 方法时，这些类的实例会自动解包。

Example

// 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

Class Binary

Class ByteArray

Instance Methods

Instance Properties

Static Methods

Class ByteString

Instance Methods

Instance Properties

Static Methods

Class String

Instance Methods

Binary ()

ByteArray 和 ByteString 的抽象基类。二进制类型仅用于确认 Binary 的 ByteString 和 ByteArray 实例。

ByteArray (contentOrLength, [charset])

构造一个可写和可生长的字节数组。

如果此构造函数的第一个参数是一个数字，它将指定 ByteArray 的初始长度（以字节为单位）。否则，参数定义了 ByteArray 的内容。如果参数是一个 String，则构造函数需要第二个参数，其中包含 String 的编码名称。如果没有参数调用，则返回一个空的 ByteArray。

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. byteAt (offset)

以 ByteArray 的形式返回给定偏移量处的字节。

Example

var ba = new ByteArray([0,1,2,4,8]);
ba.byteAt(0); // --> [ByteArray 1]

Parameters

Number offset

Returns

ByteArray

ByteArray.prototype. charAt (offset)

以 ByteArray 的形式返回给定偏移量处的字节。

Example

var ba = new ByteArray([0,1,2,4,8]);
ba.charAt(0); // --> [ByteArray 1]

Parameters

Number offset

Returns

ByteArray

ByteArray.prototype. charCodeAt (offset)

在给定的偏移量处返回 charcode。

Example

var ba = new ByteArray([0,1,2,4,8]);
ba.charCodeAt(0); // --> 0

Parameters

Number offset

Returns

Number

ByteArray.prototype. concat (args...)

返回由与给定的 ByteString，ByteArray 和 Array 值连接的自身组成的 ByteArray。

Parameters

Binary...|Array... args...

one or more elements to concatenate

Returns

ByteArray

a new ByteArray

ByteArray.prototype. copy (start, end, target, targetOffset)

将从此对象开始和停止之间的一系列字节复制到给定目标偏移量处的另一个 ByteArray。

Parameters

Number start
Number end
ByteArray target
Number targetOffset

ByteArray.prototype. decodeToString (encoding)

使用给定的编码返回解码为字符串的 ByteArray

Example

var ba = new ByteArray([240, 159, 152, 130]);
console.log(ba.decodeToString("UTF-8")); // prints 😂

Parameters

String encoding

the name of the encoding to use

ByteArray.prototype. every (callback, thisObj)

测试数组中的所有元素是否都通过了由提供的函数实现的测试。

Example

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

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)

返回包含此回调函数返回 true 的此 ByteArray 元素的 ByteArray。

Example

var ba = "hello world".toByteArray();
var bf = ba.filter(function(byte) { return byte > 110 });
bf.decodeToString(); // returns "owor"

Parameters

Function callback

the filter function
Object thisObj

optional this-object for callback

Returns

ByteArray

a new ByteArray

ByteArray.prototype. forEach (fn, thisObj)

为 ByteArray 中的每个元素应用一个函数。

Example

var ba = "hello world".toByteArray();
// prints 104, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100
ba.forEach(function(byte) { console.log(byte) });

Parameters

Function fn

the function to call for each element
Object thisObj

optional this-object for callback

ByteArray.prototype. get (offset)

以整数形式返回给定偏移量处的字节。 get(offset) 与括号 [offset] 的索引类似。

Example

var ba = new ByteArray([0,255]);
print(ba[0]); // prints 0

Parameters

Number offset

Returns

Number

ByteArray.prototype. indexOf (sequence, start, stop)

返回序列第一次出现的索引（一个 Number 或一个 ByteString 或任意长度的 ByteArray），如果没有找到，则返回 -1。如果指定了开始和 / 或停止，则只搜索索引开始和停止之间的元素。

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)

返回序列的最后一次出现的索引（一个 Number 或一个 ByteString 或任何长度的 ByteArray），如果没有找到，则返回 -1 。如果指定了开始和 / 或停止，则只搜索索引开始和停止之间的元素。

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

以字节为单位的长度。该属性是可写的。将其设置为高于当前值的值将使用 0 填充新插槽，将其设置为较低的值会截断字节数组。

ByteArray.prototype. map (callback, thisObj)

返回一个新的 ByteArray，其内容是使用原始 ByteArray 的每个元素调用提供的函数的结果。

Example

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]

Parameters

Function callback

the callback
Object thisObj

optional this-object for callback

Returns

ByteArray

a new ByteArray

ByteArray.prototype. pop ()

从数组中删除最后一个元素并返回该元素。

Example

var ba = new ByteArray([0,1,2,4,8]);
ba.pop() === 8; // --> true

Returns

Number

ByteArray.prototype. push (num...)

追加给定的元素并返回数组的新长度。

Example

var ba = new ByteArray([0,1,2,4,8]);
ba.push(16);
console.log(ba.toArray()); // [0, 1, 2, 4, 8, 16]

Parameters

Number... num...

one or more numbers to append

Returns

Number

the new length of the ByteArray

ByteArray.prototype. reduce (callback, initialValue)

将此函数应用于此 ByteArray 中的每个元素，从左到右将其内容减少为单个值。

Example

var ba = new ByteArray([0,1,2,3,4,5,6,7,8]);
ba.reduce(function(prev, curr) { return prev + curr; }); // --> 36

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)

将一个函数应用于此ByteArray中从最后一个元素开始的每个元素，以将其内容减少为单个值。

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 ()

颠倒 ByteArray 的内容。

Example

var ba = new ByteArray([0,1,2,3,4,5,6,7,8]);
ba.reverse();
print(ba[0] == 8); // --> true

Returns

ByteArray

this ByteArray with its elements reversed

ByteArray.prototype. set (offset, value)

设置给定偏移量处的字节。 set(offset，value) 与括号 [offset] = value 的索引类似。

Example

var ba = new ByteArray([0,255]);
ba[0] = 64;
print(ba[0]); // prints 64

Parameters

Number offset
Number value

ByteArray.prototype. shift ()

从 ByteArray 中移除第一个元素并返回该元素。此方法更改 ByteArray 的长度。

Example

var ba = new ByteArray([0,1,2,4,8]);
ba.shift();
console.log(ba.toArray()); // [1, 2, 4, 8]

Returns

Number

the removed first element

ByteArray.prototype. slice (begin, end)

返回包含此 ByteArray 一部分的新 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)

测试数组中的某个元素是否通过了由提供的函数实现的测试。

Example

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

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)

在原地排列 ByteArray 的内容。

Example

var ba = "hello world".toByteArray();
ba.sort();
ba.decodeToString() // --> "dehllloorw"

Parameters

Function comparator

the function to compare entries

Returns

ByteArray

this ByteArray with its elements sorted

ByteArray.prototype. splice (index, howMany, elements...)

更改 ByteArray 的内容，在删除旧元素的同时添加新元素。

Example

var ba = new ByteArray([0,1,2,4,8]);
ba.splice(2,2);
console.log(ba.toArray()); // [0, 1, 8]

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)

在分隔符处分割，可以通过 Number，ByteString，ByteArray 或先前的 Array（包含多个分隔符，即“在任何这些分隔符处分割”）来分隔。分隔符可以具有任意大小。

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 ()

将包含字节的数组作为数字返回。

ByteArray.prototype. toByteArray ()

ByteArray.prototype. toByteString ()

ByteArray.prototype. toString ()

返回 ByteArray 的字符串表示形式。

Example

var ba = new ByteArray([0,1,2,4,8]);
console.log(ba.toString()); // prints '[ByteArray 5]'

ByteArray.prototype. unshift (num...)

将一个或多个元素添加到 ByteArray 的开头并返回其新长度。

Example

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]

Parameters

Number... num...

one or more numbers to append

Returns

Number

the new length of the ByteArray

ByteArray.prototype. unwrap ()

从 ByteArray 解开基础 Java byte []。它可以传递给需要一个字节数组的Java方法。

Returns

byte[]

a native Java byte array

ByteArray. wrap (bytes)

为 ByteArray 构造函数创建 ByteArray 包装器，而不创建新副本。对 ByteArray 实例所做的任何更改都将应用于原始字节数组。

Example

// writes a java.security.Key byte[] to a file;
fs.write("id_dsa.pub", ByteArray.wrap(publicKey.getEncoded()));

Parameters

Binary bytes

a Java byte array or Binary instance

Returns

ByteArray

a ByteArray wrapping the argument

ByteString (content, charset)

构造一个不可变的字节字符串。

如果第一个参数是一个字符串，则构造函数需要第二个参数包含该字符串的编码名称。如果没有参数调用，则返回一个空的 ByteString。

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)

以 ByteString 的形式返回给定偏移量处的字节。

Parameters

Number offset

Returns

ByteString

ByteString.prototype. charAt (offset)

以 ByteString 的形式返回给定偏移量处的字节。

Parameters

Number offset

Returns

ByteString

ByteString.prototype. charCodeAt (offset)

在给定的偏移量处返回 charcode。

Parameters

Number offset

Returns

Number

ByteString.prototype. concat (args...)

返回由与给定的 ByteString，ByteArray 和 Array 值连接的自身组成的 ByteString。

Parameters

Binary...|Array... args...

one or more elements to concatenate

Returns

ByteString

a new ByteString

ByteString.prototype. copy (start, end, target, targetStart)

将从此 ByteString 开始和停止之间的一系列字节复制到给定 targetStart 偏移量处的目标 ByteArray。

Parameters

Number start
Number end
ByteArray target
Number targetStart

ByteString.prototype. decodeToString (charset)

将此ByteString作为字符串返回，并使用给定的字符集进行解码。

Parameters

String charset

the name of the string encoding

ByteString.prototype. get (offset)

以 ByteString 的形式返回给定偏移量处的字节。 get(offset) 与括号 [offset] 的索引类似。

Parameters

Number offset

Returns

ByteString

ByteString.prototype. indexOf (sequence, start, stop)

返回序列第一次出现的索引（一个 Number 或一个 ByteString 或任意长度的 ByteArray），如果没有找到，则返回 -1。如果指定了开始和 / 或停止，则只搜索索引开始和停止之间的元素。

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)

返回序列的最后一次出现的索引（一个 Number 或一个 ByteString 或任何长度的 ByteArray），如果没有找到，则返回 -1。如果指定了开始和 / 或停止，则只搜索索引开始和停止之间的元素。

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. length

以字节为单位的长度。此属性是只读的。将它设置为一个值默默地失败。

ByteString.prototype. slice (begin, end)

返回包含此ByteString一部分的新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)

在分隔符处分割，可以通过 Number，ByteString，ByteArray 或先前的 Array（包含多个分隔符，即“在任何这些分隔符处分割”）来分隔。分隔符可以具有任意大小。

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 ()

将包含字节的数组作为数字返回。

ByteString.prototype. toByteArray ()

返回此不可变 ByteString 的字节副本的字节作为可变 ByteArray。

Returns

ByteArray

ByteString.prototype. toByteString ()

返回这个 ByteString 本身。

ByteString.prototype. toString ()

返回一个调试表示，如 “[ByteSTring 10]”，其中 10 是此 ByteString 的长度。

ByteString.prototype. unwrap ()

从 ByteString 解开基础 Java byte []。它可以传递给需要一个字节数组的 Java 方法。

Returns

byte[]

a native Java byte array

ByteString. wrap (bytes)

为 ByteString 构造函数创建 ByteString 包装器，而不创建新副本。

Parameters

Binary bytes

a Java byte array or Binary instance

Returns

ByteString

a ByteString wrapping the argument

String

不通过此模块导出为构造函数。

String.prototype. toByteArray (charset)

使用指定的编码将字符串转换为可变的 ByteArray。

Example

var ba = "hello world".toByteArray();

Parameters

String charset

the name of the string encoding. Defaults to 'UTF-8'

Returns

ByteArray

a ByteArray representing the string

String.prototype. toByteString (charset)

使用指定的编码将字符串转换为不可变的 ByteString。

Example

var bs = "hello world".toByteString();

Parameters

String charset

the name of the string encoding. Defaults to 'UTF-8'

Returns

ByteString

a ByteString representing the string