Class: UTF8

Layout~UTF8(maxSpanopt, propertyopt)

Contain a UTF8 string with implicit length.

Factory: utf8

NOTE Because the length is implicit in the size of the buffer this layout should be used only in isolation, or in a situation where the length can be expressed by operating on a slice of the containing buffer.

Constructor

new UTF8(maxSpanopt, propertyopt)

Parameters:
Name Type Attributes Description
maxSpan Number <optional>

the maximum length allowed for encoded string content. If not provided there is no bound on the allowed content.
property String <optional>

initializer for property.
Source:

Extends

Members

maxSpan

The maximum span of the layout in bytes.

Positive values are generally expected. Zero is abnormal. Attempts to encode or decode a value that exceeds this length will throw a RangeError.

A negative value indicates that there is no bound on the length of the content.

Source:

property

The property name used when this layout is represented in an Object.

Used only for layouts that decode to Object instances. If left undefined the span of the unnamed layout will be treated as padding: it will not be mutated by encode nor represented as a property in the decoded Object.

Inherited From:
Source:

span

The span of the layout in bytes.

Positive values are generally expected.

Zero will only appear in Constants and in Sequences where the count is zero.

A negative value indicates that the span is value-specific, and must be obtained using getSpan.

Inherited From:
Source:

Methods

decode(b, offsetopt) → {Number|Array|Object}

Decode from a Buffer into an JavaScript value.

Parameters:
Name Type Attributes Description
b Buffer

the buffer from which encoded data is read.
offset Number <optional>

the offset at which the encoded data starts. If absent a zero offset is inferred.
Overrides:
Source:
Returns:
  • the value of the decoded data.
Type
Number | Array | Object

encode(src, b, offsetopt) → {Number}

Encode a JavaScript value into a Buffer.

Parameters:
Name Type Attributes Description
src Number | Array | Object

the value to be encoded into the buffer. The type accepted depends on the (sub-)type of Layout.
b Buffer

the buffer into which encoded data will be written.
offset Number <optional>

the offset at which the encoded data starts. If absent a zero offset is inferred.
Overrides:
Source:
Returns:
  • the number of bytes encoded, including the space skipped for internal padding, but excluding data such as lengths when stored externally. This is the adjustment to offset producing the offset where data for the next layout would be written.
Type
Number

fromArray(values) → {Object|undefined}

Create an object from layout properties and an array of values.

NOTE This function returns undefined if invoked on a layout that does not return its value as an Object. Objects are returned for things that are a Structure, which includes variant layouts if they are structures, and excludes Unions. If you want this feature for a union you must use getVariant to select the desired layout.

Parameters:
Name Type Description
values Array

an array of values that correspond to the default order for properties. As with decode layout elements that have no property name are skipped when iterating over the array values. Only the top-level properties are assigned; arguments are not assigned to properties of contained layouts. Any unused values are ignored.
Inherited From:
Source:
Returns:
Type
Object | undefined

getSpan(b, offsetopt) → {Number}

Calculate the span of a specific instance of a layout.

Parameters:
Name Type Attributes Description
b Buffer

the buffer that contains an encoded instance.
offset Number <optional>

the offset at which the encoded instance starts. If absent a zero offset is inferred.
Overrides:
Source:
Throws:
  • if the length of the value cannot be determined.
Type
RangeError
Returns:
  • the number of bytes covered by the layout instance. If this method is not overridden in a subclass the definition-time constant span will be returned.
Type
Number

makeDestinationObject()

Function to create an Object into which decoded properties will be written.

Used only for layouts that decode to Object instances, which means:

If left undefined the JavaScript representation of these layouts will be Object instances.

See bindConstructorLayout.

Inherited From:
Source:

replicate(property) → {module:Layout~Layout}

Replicate the layout using a new property.

This function must be used to get a structurally-equivalent layout with a different name since all Layout instances are immutable.

NOTE This is a shallow copy. All fields except property are strictly equal to the origin layout.

Parameters:
Name Type Description
property String

the value for property in the replica.
Inherited From:
Source:
Returns:
  • the copy with property set to property.
Type
module:Layout~Layout