Class: Structure

Layout~Structure(fields, propertyopt, decodePrefixesopt)

Represent a contiguous sequence of arbitrary layout elements as an Object.

Factory: struct

NOTE The span of the structure is variable if any layout in fields has a variable span. When encoding we must have a value for all variable-length fields, or we wouldn't be able to figure out how much space to use for storage. We can only identify the value for a field when it has a property. As such, although a structure may contain both unnamed fields and variable-length fields, it cannot contain an unnamed variable-length field.

Constructor

new Structure(fields, propertyopt, decodePrefixesopt)

Parameters:
Name Type Attributes Description
fields Array.<module:Layout~Layout>

initializer for fields. An error is raised if this contains a variable-length field for which a property is not defined.
property string <optional>

initializer for property.
decodePrefixes module:Layout~Boolean <optional>

initializer for property.
Source:
Throws:
  • if fields contains an unnamed variable-length layout.
Type
Error

Extends

Members

decodePrefixes

Control behavior of decode() given short buffers.

In some situations a structure many be extended with additional fields over time, with older installations providing only a prefix of the full structure. If this property is true decoding will accept those buffers and leave subsequent fields undefined, as long as the buffer ends at a field boundary. Defaults to false.

Source:

fields :Array.<module:Layout~Layout>

The sequence of Layout values that comprise the structure.

The individual elements need not be the same type, and may be either scalar or aggregate layouts. If a member layout leaves its property undefined the corresponding region of the buffer associated with the element will not be mutated.

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

Implement encode for Structure.

If src is missing a property for a member with a defined property the corresponding region of the buffer is left unmodified.

Overrides:
Source:

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.
Overrides:
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

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

Get access to the layout of a given property.

Parameters:
Name Type Description
property String

the structure member of interest.
Source:
Returns:
  • the layout associated with property, or undefined if there is no such property.
Type
module:Layout~Layout

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:

offsetOf(property) → {Number}

Get the offset of a structure member.

Parameters:
Name Type Description
property String

the structure member of interest.
Source:
Returns:
  • the offset in bytes to the start of property within the structure, or undefined if property is not a field within the structure. If the property is a member but follows a variable-length structure member a negative number will be returned.
Type
Number

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