Flusspferd API and module docs

mixin binary.Binary

Description

Shared behaviour between ByteArrays and ByteStrings.

In Flusspferd, Binary is a class in its own right – albeit one that you can’t constrauct from directly form javascript – which is in the prototype chain of which both ByteArrays and ByteStrings.

Please note however that this is an extension to the CommonJS spec, so if you rely in this behaviour your code will become non-portable.

A note on range arguments

A number of methods accept on blobs accept ranges, either in the form start, end (slice) or start, length (binary.ByteString#substr or binary.ByteArray#splice). Most of these parameters behave predictably, but it is worth noting that any of the values of a range can be negative, in which case it counts backwards from the end. See binary.Binary.range and binary.Binary.lengthRange for more details.

Methods

Class methods

  • lengthRange #

    binary.Binary.lengthRange(start[, howMany]) ⇒ [Number,Number]

    Note: This is not an actual callable method, it just describes behaviour.

    A range of howMany bytes starting at position start.

    start can be negative, in which case it counts backwards from the end of the blob. howMany cannot be negative, and will never overflow past the end of the blob.

    For example, given a blob which is 10 bytes long, all the following ranges are the same, bytes 3,4 and 5:

    3,3
-7,3

    This is how Array#splice and String#substr behaves.

  • range #

    binary.Binary.range(start[, end]) ⇒ [Number,Number]

    Note: This is not an actual callable method, it just describes behaviour.

    Bytes ranging from [start,end) (start is included, end is excluded). If end is not provided, range from start to the end of the blob.

    Either start or end can be negative, in which case they count backwards from the end of the blob. For example, given a blob which is 10 bytes long, all the following ranges are the same, bytes 3,4 and 5:

    3,6
3,-4
-7,6
-7,-4

    If end is less than start (after both values have been corrected for being negative and clamped to the length of the blob) then end is set to start, meaning a range that covers 0 bytes is created.

    This described behaviour is how Array#slice behaves. String#substring behaves simiarly except for negative values.

Instance methods

  • byteAt #

    binary.Binary#byteAt(index) ⇒ binary.ByteString
    • index (Number) – byte to get

    Get the byte at the specified index as a ByteString. To get the actual byte value, use get(index).

    Currently CommonJS has speced this to return a ByteString of length one, but this might well change in a future version of the spec.

    Aliased as: binary.Binary#charAt

  • charAt #

    binary.Binary#charAt(index) ⇒ binary.ByteString
    • index (Number) – byte to get

    Provided for compatibility with String. Return a ByteString of length one for the given index. Will throw a RangeError if index is not valid.

    Alias of: binary.Binary#byteAt

  • concat #

    binary.Binary#concat(args...) ⇒ binary.Binary

    Concatenate together this blob and the provided arguments into a new blob of the same type as the invocant.

    Each argument must be a Byte, an Array of Bytes or another blob.

  • decodeToString #

    binary.Binary#decodeToString([charset="UTF-8"]) ⇒ String
    • charset (String) – character set to interpret invocant as.

    Decode the blob to a string of characters by using the encodings module.

  • get #

    binary.Binary#get(index) ⇒ Byte
    • index (Number) – byte to get

    Return the actualy byte value at index – i.e. a Number between 0 and 255. Can throw a RangeError.

    Aliased as: binary.ByteString#charCodeAt

  • indexOf #

    binary.Binary#indexOf(byte[, start=0 [, stop]]) ⇒ Array
    • byte (Byte) – byte to search for
    • start (Number) – Start of range to search for byte in. Default 0
    • stop (Number) – End of range.

    Return the index of the first occurance of byte or -1 if it cannot be found.

    [start,stop) form a binary.Binary.range.

  • lastIndexOf #

    binary.Binary#lastIndexOf(byte[, start=0 [, stop]]) ⇒ Array
    • byte (Byte) – byte to search for
    • start (Number) – Index to start searching for byte.
    • stop (Number) – Index to stop searching at. Defaults to last byte the blob

    Return the index of the lat occurance of byte in the specified range, or -1 if it cannot be found.

    [start,stop) form a binary.Binary.range.

  • slice #

    binary.Binary#slice(start[, end]) ⇒ binary.Binary
    • start (Number) – start index
    • end (Number) – end index. Defaults to end of blob

    Return a slice of the blob containing the range [start, end).

    The returned blob is of the same type as the invocant, i.e. a ByteString when called on a ByteString.

  • split #

    binary.Binary#split(delim[, options]) ⇒ [binary.Binary…]
    • delim (Byte | Array | binary.Binary) – Byte value to split on
    • options (Object) – options dictionary.

    Split the blob into an array of blobs (of the same type as the invocant) about on a set of (single byte) delimiters. If delim is an array, each element must be something accepted by the binary.ByteString constructor.

    The behaviour of this function can be tweaked by the following keys in the options dictionary argument:

    • count (Number): Maximum number of elements in the return array. If count is 1 you will get an array containg just a copy of this blob.
    • includeDelimiter (Boolean): should the matched delimiter be added as an element in the return array

  • toArray #

    binary.Binary#toArray() ⇒ Array

    Return an array containing the contents of this blob as an array of bytes (Numbers).

  • toByteArray #

    binary.Binary#toByteArray() ⇒ binary.ByteArray

    Create a new copy of this blob as a mutable ByteArray. If it is already a ByteArray, a new copy will be created.

  • toByteString #

    binary.Binary#toByteString() ⇒ binary.ByteString.

    Coerce the blob into a ByteString. If it is already one it will be returned directly as ByteStrings are immutable.