The AdaptValue class wraps around the MUFL value. That is, each MUFL value can be represented in TypeScript code as an instance of the AdaptValue class.

It inherits from the (AdaptObject), which means it has the same memory management API as AdaptEvaluationUnit and AdaptPacketContext. The value must be destroyed using the Destroy method or using the lifetime object that is capable of deleting all the objects attached to it (see AdaptObjectLifetime).

Hierarchy

Table of contents

Constructors

Accessors

Methods

Constructors

constructor

• new AdaptValue(lt, from)

Create an instance of the AdaptValue class.

Throws

An error if ADAPT is not initialized (see Initialize or InitializeAsync)

Example

Creating a value from Convertible

AdaptEnvironment.InitializeAsync().then(() => {
     const lifetime = new AdaptObjectLifetime();
     const number_value    = new AdaptValue(lifetime, 45);             // 45
     const string_value    = new AdaptValue(lifetime, "hello world");  // "hello world"
     const true_value      = new AdaptValue(lifetime, true);           // TRUE
     const false_value     = new AdaptValue(lifetime, false);          // NIL
     const undefined_value = new AdaptValue(lifetime, undefined);      // NIL
     const null_value      = new AdaptValue(lifetime, null);           // NIL

     lifetime.Finalize(); // destroy all values
})

Example

Deep copy of the value

AdaptEnvironment.InitializeAsync().then(() => {
     const lifetime = new AdaptObjectLifetime();
     const value = new AdaptValue(lifetime, 45);
     const reference_copy = value;
     const cloned_value = new AdaptValue(undefined, value); // passing undefined lifetime so the value will not be deleted on the lifetime.Finalize() call
     
     // here is another way of cloning the value
     const another_cloned_value = value.Clone(undefined);

     lifetime.Finalize(); // destroys both value and reference_copy. However, cloned_value is not deleted and is still valid because the deep copy of the value was created

     cloned_value.Destroy(); // cloned_value is no longer valid after this line
     another_cloned_value.Destroy();
})

Parameters

Name Type Description
lt undefined | AdaptObjectLifetime Lifetime object to attach a new value to. If undefined is passed, the value must be destroyed later manually using Destroy.
from AdaptValueOrConvertible | AdaptValue The value to be created. If AdaptValue is passed, the value is cloned and attached to the given lifetime object.

Overrides

AdaptObject.constructor

Defined in

adapt_js/src/adapt.ts:497

Accessors

lifetime

• get lifetime(): undefined | AdaptObjectLifetime

Returns

undefined | AdaptObjectLifetime

Inherited from

AdaptObject.lifetime

Defined in

common/dist/memory_management/adapt_object_lifetime.d.ts:54

• set lifetime(lt): void

Parameters

Name Type
lt undefined | AdaptObjectLifetime

Returns

void

Inherited from

AdaptObject.lifetime

Defined in

common/dist/memory_management/adapt_object_lifetime.d.ts:55

Methods

Attach

▸ Attach(lt?): AdaptValue

Attach an object to the given lifetime object.

When a lifetime object has already been defined, first detach the object from the previous lifetime object, then attach it to the new one.

Example

AdaptEnvironment.InitializeAsync().then(() => {
     const lifetime = new AdaptObjectLifetime();
     const lifetime1 = new AdaptObjectLifetime();
     const value = new AdaptValue(lifetime, 5);
     value.Attach(lifetime1);
     lifetime.Finalize(); // value is not destroyed by this call
     lifetime1.Finalize(); // value is destroyed
})

Parameters

Name Type Description
lt? AdaptObjectLifetime Lifetime to attach object to

Returns

AdaptValue

Inherited from

AdaptObject.Attach

Defined in

common/dist/memory_management/adapt_object_lifetime.d.ts:76

Clone

▸ Clone(lifetime?): AdaptValue

Create a deep copy of the AdaptValue.

Throws

An error if ADAPT is not initialized (see Initialize or InitializeAsync)

Example

AdaptEnvironment.InitializeAsync().then(() => {
     const lifetime = new AdaptObjectLifetime();
     const value = new AdaptValue(lifetime, 44);
     const value_cloned = value.Clone(undefined);
     lifetime.Finalize();

     // value_cloned is still accessible because it was cloned and attached to the `undefined` lifetime object.

     value_cloned.Destroy();  
   
})

Example

Missing clone

AdaptEnvironment.InitializeAsync().then(() => {
     const value = new AdaptValue(undefined, 5);
     const valueCopyRef = value;
     value.Destroy();

     // valueCopyRef is invalid because the object it references within the C++ code has been destroyed.
})

Parameters

Name Type
lifetime? AdaptObjectLifetime

Returns

AdaptValue

A cloned AdaptValue

Overrides

AdaptObject.Clone

Defined in

adapt_js/src/adapt.ts:888

Destroy

▸ Destroy(): void

Destroy the C++ object. After calling this method, the object reference is no longer valid and, thus, can’t be used.

Example

AdaptEnvironment.InitializeAsync().then(() => {
     const lifetime = new AdaptObjectLifetime();
     const value = new AdaptValue(lifetime, 5);
     const anotherValue = value;
     const valueCloned = value.Clone(undefined);
     value.Destroy();
     // Both `value` and `anotherValue` can't be used because they are pointing to the same C++ object that has been deleted.
     // However, `valueCloned` is valid because it points to another (cloned) C++ object.
     valueCloned.Destroy();
     lifetime.Finalize();
})

Returns

void

Inherited from

AdaptObject.Destroy

Defined in

common/dist/memory_management/adapt_object_lifetime.d.ts:34

Detach

▸ Detach(): AdaptValue

Detach the value from the lifetime object.

Example

AdaptEnvironment.InitializeAsync().then(() => {
     const lifetime = new AdaptObjectLifetime();
     const value = new AdaptValue(lifetime, 5);
     value.Detach(); // value must be destroyed manually now
     lifetime.Finalize(); // value is not destroyed by this call
     value.Destroy();
})

Returns

AdaptValue

Inherited from

AdaptObject.Detach

Defined in

common/dist/memory_management/adapt_object_lifetime.d.ts:92

Equals

▸ Equals(rhs): boolean

Enable comparing two underlying MUFL values. Unlike the simple ‘==’ operator called on AdaptValue class that is comparing just references to the object, this method compares the underlying MUFL values.

Example

AdaptEnvironment.InitializeAsync().then(() => {
     const lifetime = new AdaptObjectLifetime();
     const value_lhs = new AdaptValue(lifetime, "hello world");
     const value_rhs = new AdaptValue(lifetime, "hello world");
     const value_clone = value_rhs.Clone(lifetime);
     
     if(value_lhs.Equals(value_rhs) && value_lhs.Equals(value_clone) && value_lhs.Equals("hello world")) 
         console.log("YES!");

     lifetime.Finalize();

})

Parameters

Name Type Description
rhs AdaptValueOrConvertible The right-hand side of the equal expression.

Returns

boolean

True if values are equal

Defined in

adapt_js/src/adapt.ts:821

GetBinary

▸ GetBinary(): Buffer

Convert an AdaptValue to a binary buffer.

Throws

An error if the original value is not of domain BINARY

Example

AdaptEnvironment.InitializeAsync().then(() => {
     const lifetime = new AdaptObjectLifetime();
     const packet = AdaptEnvironment.EmptyPacket(lifetime, false);
     const value_bin = packet.NewBinaryFromHex("abcdef");
     const value_str = new AdaptValue(lifetime, "hello world");

     const bin_buf = value_bin.GetBinary();

     try {
         value_str.GetBinary(); // fails because value_str is not of domain BINARY
     } catch (e) {}

     lifetime.Finalize();
})

Returns

Buffer

A binary buffer if the original value is of domain BINARY, otherwise throws an error

Defined in

adapt_js/src/adapt.ts:766

GetBoolean

▸ GetBoolean(): boolean

Convert an AdaptValue to a boolean.

Throws

An error if the original value is neither TRUE nor NIL.

Example

AdaptEnvironment.IniializeAsync().then(() => {
     const lifetime = new AdaptObjectLifetime();
     const value_false = new AdaptValue(lifetime, false);
     const value_true = new AdaptValue(lifetime, true);
     if (!value_false.GetBoolean() && value_true.GetBoolean())
         console.log("YES!");

     const value_string = new AdaptValue(lifetime, "hello world");
     try {
         value_string.GetBoolean(); // throws an error because value_string is neither TRUE nor NIL.
     } catch (e) {}

     lifetime.Finalize();
})

Returns

boolean

True if value is TRUE, false if value is NIL, otherwise throws an error

Defined in

adapt_js/src/adapt.ts:736

GetHash

▸ GetHash(): AdaptValue

Calculate the BLAKE2 hash of the MUFL value. Create a new AdaptValue attaching it to the same lifetime as the original value.

Note: When the original value lifetime is undefined, the hash value must be deleted manually.

Example

AdaptEnvironment.InitializeAsync().then(() => {
     const lifetime = new AdaptObjectLifetime();
     const value = new AdaptValue(lifetime, 50);
     const value_hash = value.GetHash(); // value_hash has the same lifetime as the original value
     console.log(value_hash.Visualize());

     lifetime.Finalize();
})

Returns

AdaptValue

A hash code of the value represented as an AdaptValue of domain HASH_CODE

Defined in

adapt_js/src/adapt.ts:588

GetKeys

▸ GetKeys(): AdaptValue[]

Get a list of reducers of the MUFL value.

Example

AdaptEnvironment.InitializeAsync().then(() => {
     const packet = AdaptEnvironment.EmptyPacket(undefined, true);
     const dict = packet.CreateDictionary().Mutate(1, "hello world").Mutate("reducer", "product");
     const reducers = dict.GetReducers();

     console.log(reducers[0].Visualize()); // prints 1
     console.log(reducers[1].Visualize()); // prints "reducer"
})

#### Returns

[`AdaptValue`](/release/0.2/AdaptValue.html)[]

A list of reducers of the MUFL value

#### Defined in

[adapt_js/src/adapt.ts:908](https://github.com/adapt-toolkit/mufl-poc-cpp/blob/53fcb139/addon/adapt_js/src/adapt.ts#L908)

___

### GetNumber

▸ **GetNumber**(): `number`

Convert an AdaptValue to a number.

**`Throws`**

An error if the original value is not integer

**`Example`**

```ts
AdaptEnvironment.InitializeAsync().then(() => {
     const lifetime = new AdaptObjectLifetime();
     const value = new AdaptValue(lifetime, 10);
     const n = value.GetNumber(); // n == 10
     const value_str = new AdaptValue(lifetime, "hello world");
     try {
         value_str.GetNumber(); // throws an error because value_str does not container an integer value
     } catch (e) {}

     lifetime.Finalize();
})

Returns

number

A number representation if the value was originally a MUFL value of domain INTEGER, otherwise throws an error

Defined in

adapt_js/src/adapt.ts:707

GetPacket

▸ GetPacket(): AdaptPacketContext

Return the packet the value is attached to.

Example

AdaptEnvironment.InitializeAsync().then(() => {
     const lifetime = new AdaptObjectLifetime();
     const packet = AdaptEnvironment.EmptyPacket(lifetime, true);
     const dict = packet.CreateDictionary();
     const packet1 = dict.GetPacket(); // returns the same packet as 'packet'

     lifetime.Finalize();
})

Returns

AdaptPacketContext

The packet the value is attached to

Defined in

adapt_js/src/adapt.ts:681

IsNil

▸ IsNil(): boolean

Check whether the MUFL value managed by the AdaptValue is NIL.

Example

AdaptEnvironment.InitializeAsync().then(() => {
     const lifetime = new AdaptObjectLifetime();
     const value_true = new AdaptValue(lifetime, true);
     const value_false = new AdaptValue(lifetime, false);
     const value_undef = new AdaptValue(lifetime, undefined);

     const value_str = new AdaptValue(lifetime, "hello world");

     if (!value_true.IsNil() && value_false.IsNil() && value_undef.IsNil() && !value_str.IsNil())
         console.log("YES!");

     lifetime.Finalize();
})

Returns

boolean

True if the underlying MUFL value is NIL, otherwise false

Defined in

adapt_js/src/adapt.ts:795

Less

▸ Less(rhs): boolean

Enable comparing two underlying MUFL values. Return true if this value is less than the right-hand-side value.

Example

AdaptEnvironment.InitializeAsync().then(() => {
     const lifetime = new AdaptObjectLifetime();
     const value_lhs = new AdaptValue(lifetime, 1);
     const value_rhs = new AdaptValue(lifetime, 2);
     
     if (value_lhs.Less(value_rhs))
         console.log("YES!");

     lifetime.Finalize();
})

Parameters

Name Type Description
rhs AdaptValueOrConvertible The right-hand side of the less operator

Returns

boolean

True if the value is less than the right-hand-side value

Defined in

adapt_js/src/adapt.ts:847

Mutate

▸ Mutate(reducer, product): AdaptValue

Mutate the value of the reducible MUFL value (dictionary, string, binary). This operation is immutable, which means it first copies the original value, mutates it, and then returns. So, the original value is never changed.

Example

AdaptEnvironment.InitializeAsync().then(() => {
     const lifetime = new AdaptObjectLifetime();
     const packet = AdaptEnvironment.EmptyPacket(lifetime, true);
     const dict = packet.CreateDictionary(); // contains empty dictionary: (,)
     const dict1 = dict.Mutate(1, "hello world"); // contains (1 -> "hello world") 
     const dict2 = dict1.Mutate("a", "value"); // contains (1 -> "hello world", "a" -> "value")
     
     // multiple mutations 
     const dict3 = dict2.Mutate(2, false).Mutate(3, true).Mutate(4, "lalala");

     lifetime.Finalize();
})

Parameters

Name Type Description
reducer AdaptValueOrConvertible A reducer (key) value
product AdaptValueOrConvertible A product value

Returns

AdaptValue

A copy of the original value with a mutated element

Defined in

adapt_js/src/adapt.ts:658

Reduce

▸ Reduce(reducer): AdaptValue

Enable reduction of the AdaptValue. Note: the lifetime of the resulting value is the same as the THIS value lifetime.

Example

String reduction

AdaptEnvironment.InitializeAsync().then(() => {
     const lifetime = new AdaptObjectLifetime();
     const value = new AdaptValue( lifetime, "hello world" );
     const product = value.Reduce( 6 ); // 'w'
     console.log(product.Visualize()); // print 'w' to console 

     lifetime.Finalize();
})

Example

Dictionary reduction

AdaptEnvironment.InitializeAsync().then(() => {
     const lifetime = new AdaptObjectLifetime();
     const packet = AdaptEnvironment.EmtpyPacket(lifetime, true);
     const dict = packet.CreateDictionary().Mutate(1, "hello world").Mutate("reducer", "product");
     console.log(dict.Reduce("reducer").Visualize()); // prints 'product'
     console.log(dict.Reduce(1).Visualize()); // prints "hello world"
     
     // reduction could also be nested
     console.log(dict.Reduce("reducer").Reduce(0).Visualize()); // prints 'p'       
     lifetime.Finalize();
})

Parameters

Name Type
reducer AdaptValueOrConvertible

Returns

AdaptValue

The result of value reduction

Defined in

adapt_js/src/adapt.ts:628

Serialize

▸ Serialize(): Buffer

Serialize the MUFL value to binary data.

Example

AdaptEnvironment.InitializeAsync().then(() => {
     const lifetime = new AdaptObjectLifetime();
     const value = new AdaptValue(lifetime, 45);
     const serialized = value.Serialize();
     const packet = AdaptEnvironment.EmptyPacket(lifetime, true);
     const value_deserialized = packet.ParseValue(serialized); // value === value_deserialized

     lifetime.Finalize();
})

Returns

Buffer

A serialized MUFL value

Defined in

adapt_js/src/adapt.ts:563

Visualize

▸ Visualize(): string

Convert any AdaptValue to its string representation. The format of the string is defined by MUFL itself. That is, the resulting string will be the same as the printed MUFL value.

Example

AdaptEnvironment.InitializeAsync().then(() => {
     const lifetime = new AdaptObjectLifetime();
     const time = AdaptEnvironment.SystemTime(lifetime);
     console.log(time.Visualize()); // print the time to the console, format of type is defined by MUFL
     // Important! AdaptValue is not implicitly converted to string
     console.log(time); // will not print the time. Instead, it prints the description of the AdaptValue class defined by TypeScript (typename, members, address in memory, etc.)
     
     lifetime.Finalize();
})

Returns

string

A string representation of the value

Defined in

adapt_js/src/adapt.ts:539