Class: Union

Layout~Union(discr, defaultLayout, propertyopt)

Represent any number of span-compatible layouts.

Factory: union

If the union has a default layout that layout must have a non-negative span. The span of a fixed-span union includes its discriminator if the variant is a prefix of the union, plus the span of its default layout.

If the union does not have a default layout then the encoded span of the union depends on the encoded span of its variant (which may be fixed or variable).

Variant layouts are added through addVariant. If the union has a default layout, the span of the layout contained by the variant must not exceed the span of the default layout (minus the span of a prefix disriminator, if used). The span of the variant will equal the span of the union itself.

The variant for a buffer can only be identified from the discriminator property (in the case of the default layout), or by using getVariant and examining the resulting VariantLayout instance.

A variant compatible with a JavaScript object can be identified using getSourceVariant.

Constructor

new Union(discr, defaultLayout, propertyopt)

Parameters:
Name Type Attributes Description
discr UnionDiscriminator | ExternalLayout | Layout

How to identify the layout used to interpret the union contents. The parameter must be an instance of UnionDiscriminator, an ExternalLayout that satisfies isCount(), or UInt (or UIntBE). When a non-external layout element is passed the layout appears at the start of the union. In all cases the (synthesized) UnionDiscriminator instance is recorded as discriminator.
defaultLayout Layout | null

initializer for defaultLayout. If absent defaults to null. If null there is no default layout: the union has data-dependent length and attempts to decode or encode unrecognized variants will throw an exception. A Layout instance must have a non-negative span, and if it lacks a property the defaultLayout will be a replica with property content.
property string <optional>

initializer for property.
Source:

Extends

Members

defaultLayout

The layout for non-discriminator content when the value of the discriminator is not recognized.

This is the value passed to the constructor. It is structurally equivalent to the second component of layout but may have a different property name.

Source:

discriminator

The interface for the discriminator value in isolation.

This a UnionDiscriminator either passed to the constructor or synthesized from the discr constructor argument. usesPrefixDiscriminator will be true iff the discr parameter was a non-offset Layout instance.

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:

registry

A registry of allowed variants.

The keys are unsigned integers which should be compatible with discriminator. The property value is the corresponding VariantLayout instances assigned to this union by addVariant.

NOTE The registry remains mutable so that variants can be added at any time. Users should not manipulate the content of this property.

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:

usesPrefixDiscriminator

true if the discriminator is the first field in the union.

If false the discriminator is obtained from somewhere else.

Source:

Methods

addVariant(variant, layout, property) → {module:Layout~VariantLayout}

Register a new variant structure within a union. The newly created variant is returned.

Parameters:
Name Type Description
variant Number

initializer for variant.
layout module:Layout~Layout

initializer for layout.
property String

initializer for property.
Source:
Returns:
Type
module:Layout~VariantLayout

configGetSourceVariant(gsv)

Function to override the implementation of getSourceVariant.

Use this if the desired variant cannot be identified using the algorithm of defaultGetSourceVariant.

NOTE The provided function will be invoked bound to this Union instance, providing local access to registry.

Parameters:
Name Type Description
gsv function

a function that follows the API of defaultGetSourceVariant.
Source:

decode()

Implement decode for Union.

If the variant is registered the return value is an instance of that variant, with no explicit discriminator. Otherwise the default layout is used to decode the content.

Overrides:
Source:

defaultGetSourceVariant(src) → {undefined|VariantLayout}

Method to infer a registered Union variant compatible with src.

The first satisified rule in the following sequence defines the return value:

  • If src has properties matching the Union discriminator and the default layout, undefined is returned regardless of the value of the discriminator property (this ensures the default layout will be used);
  • If src has a property matching the Union discriminator, the value of the discriminator identifies a registered variant, and either (a) the variant has no layout, or (b) src has the variant's property, then the variant is returned (because the source satisfies the constraints of the variant it identifies);
  • If src does not have a property matching the Union discriminator, but does have a property matching a registered variant, then the variant is returned (because the source matches a variant without an explicit conflict);
  • An error is thrown (because we either can't identify a variant, or we were explicitly told the variant but can't satisfy it).
Parameters:
Name Type Description
src Object

an object presumed to be compatible with the content of the Union.
Source:
Throws:
  • if src cannot be associated with a default or registered variant.
Type
Error
Returns:
  • as described above.
Type
undefined | VariantLayout

encode()

Implement encode for Union.

This API assumes the src object is consistent with the union's default layout. To encode variants use the appropriate variant-specific VariantLayout#encode method.

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.
Inherited From:
Source:
Returns:
Type
Object | undefined

getSourceVariant(src) → {undefined|VariantLayout}

Function to infer the variant selected by a source object.

Defaults to defaultGetSourceVariant but may be overridden using configGetSourceVariant.

Parameters:
Name Type Description
src Object

as with defaultGetSourceVariant.
Source:
Returns:

The default variant (undefined) or first registered variant that uses a property available in src.

Type
undefined | VariantLayout

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

getVariant(vb, offset) → {Object|undefined}

Get the layout associated with a registered variant.

If vb does not produce a registered variant the function returns undefined.

Parameters:
Name Type Description
vb Number | Buffer

either the variant number, or a buffer from which the discriminator is to be read.
offset Number

offset into vb for the start of the union. Used only when vb is an instance of {Buffer}.
Source:
Returns:
Type
Object | undefined

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