Dynamic Data Types

How to define objects that can hold values of any type.

Key takeaways

AnyValue Dynamic object that can hold a value of any type.
AnyValueArray Dynamic array that can hold values of any type.
AnyValueMap Dynamic map (dictionary) object that can hold values of any type.

Introduction

This tutorial explains how to use the three dynamic data types available in Pip.Services. They are AnyValue, AnyValueArray and AnyValueMap, which define dynamic types for single values (variables), arrays, and maps respectively. These types can hold any type of data, which can then be converted to several well-known formats such as integer, float, and more. This tutorial explains each of these classes and their methods through examples.

Dynamic data types

Pip.Services provides three different dynamic data types. They are AnyValue, AnyValueArray and AnyValueMap. This section explains each of them with examples.

AnyValue

This component provides a cross-language implementation of a dynamic object that can hold a value of any type. For example, it can contain an integer, a float, or a string.

// Examples
let value1 = new AnyValue(1);
let value2 = new AnyValue(123.456);
let value3 = new AnyValue("123.456");
// Examples
var value1 = new AnyValue(1);
var value2 = new AnyValue(123.456);
var value3 = new AnyValue("123.456");
// Examples
value1 := data.NewAnyValue(1)
value2 := data.NewAnyValue(123.456)
value3 := data.NewAnyValue("123.456")
// Examples
var value1 = AnyValue(1);
var value2 = AnyValue(123.456);
var value3 = AnyValue('123.456');
# Examples
value1 = AnyValue(1)
value2 = AnyValue(123.456)
value3 = AnyValue("123.456")
Not available
Pre-requisites

In order to create an AnyValue object, we need to import the corresponding class. The code below shows how to do this.

import { AnyValue } from "pip-services3-commons-nodex"
using PipServices3.Commons.Data;
import (
	data "github.com/pip-services3-go/pip-services3-commons-go/data"
)
import 'package:pip_services3_commons/pip_services3_commons.dart';
from pip_services3_commons.data import AnyValue
Not available
Create

To create an AnyValue object we need to use its constructor with the value as input parameter or clone an existing AnyValue object. The following examples show how to do this.

// Constructor
let value = new AnyValue("123.456");

// Cloning 
let value2 = value.clone();  // Returns an object of type AnyValue with value 123.456
// Constructor
var value = new AnyValue("123.456");

// Cloning 
var value2 = value.Clone();  // Returns an object of type AnyValue with value 123.456
// Constructor
value := data.NewAnyValue("123.456")

// Cloning
value2 := value.Clone() // Returns an object of type AnyValue with value 123.456
// Constructor
var value = AnyValue('123.456');

// Cloning
var value2 = value.clone(); // Returns an object of type AnyValue with value 123.456
# Constructor
value = AnyValue("123.456")

# Cloning 
value2 = value.clone()  # Returns an object of type AnyValue with value 123.456
Not available
Conversion

This component presents several methods that can be used to convert a value to different types, such as integer, long, float, double, and more. The examples below show how to use several of these methods.

import { AnyValue } from "pip-services3-commons-nodex"

let value = new AnyValue("123.456");

let value1 = value.getAsInteger();                  // Returns 123
let value2 = value.getAsLong();                     // Returns 123
let value3 = value.getAsFloat();                    // Returns 123.456   

let valueB = new AnyValue("ABC");
let value4 = valueB.getAsIntegerWithDefault(25);    // Returns 25

let value5 = value.getAsString();                   // Returns '123.456'
let value6 = value.getAsStringWithDefault("ABC");   // Returns '123.456'

valueB = new AnyValue("1");
let value7 = valueB.getAsBoolean();                 // Returns True

let valueC = new AnyValue("abc");
let value8 = valueC.getAsBooleanWithDefault(false); // Returns False

let type1 = value.getTypeCode();                    // Returns 1 (TypeCode.String)
using PipServices3.Commons.Data;

var value = new AnyValue("123.456");

var value1 = value.GetAsInteger();                  // Returns 123
var value2 = value.GetAsLong();                     // Returns 123
var value3 = value.GetAsFloat();                    // Returns 123.456                       

var valueB = new AnyValue("ABC");
var value4 = valueB.GetAsIntegerWithDefault(25);    // Returns 25

var value5 = value.GetAsString();                   // Returns '123.456'
var value6 = value.GetAsStringWithDefault("ABC");   // Returns '123.456'

valueB = new AnyValue("1");
var value7 = valueB.GetAsBoolean();                 // Returns True

var valueC = new AnyValue("abc");
var value8 = valueC.GetAsBooleanWithDefault(false); // Returns False

var type1 = value.GetTypeCode();                    // Returns TypeCode.String
import (
	"fmt"

	data "github.com/pip-services3-go/pip-services3-commons-go/data"
)

value := data.NewAnyValue("123.456")

value1 := value.GetAsInteger() // Returns 123
value2 := value.GetAsLong()    // Returns 123
value3 := value.GetAsFloat()   // Returns 123.456

valueB := data.NewAnyValue("ABC")
value4 := valueB.GetAsIntegerWithDefault(25) // Returns 25

value5 := value.GetAsString()                 // Returns '123.456'
value6 := value.GetAsStringWithDefault("ABC") // Returns '123.456'

valueB = data.NewAnyValue("1")
value7 := valueB.GetAsBoolean() // Returns True

valueC := data.NewAnyValue("abc")
value8 := valueC.GetAsBooleanWithDefault(false) // Returns False

type1 := value.TypeCode() // Returns TypeCode.String
import 'package:pip_services3_commons/pip_services3_commons.dart';

var value = AnyValue('123.456');

var value1 = value.getAsInteger(); // Returns 123
var value2 = value.getAsLong(); // Returns 123
var value3 = value.getAsFloat(); // Returns 123.456

var valueB = AnyValue('ABC');
var value4 = valueB.getAsIntegerWithDefault(25); // Returns 25

var value5 = value.getAsString(); // Returns '123.456'
var value6 = value.getAsStringWithDefault('ABC'); // Returns '123.456'

valueB = AnyValue('1');
var value7 = valueB.getAsBoolean(); // Returns True

var valueC = AnyValue('abc');
var value8 = valueC.getAsBooleanWithDefault(false); // Returns False

var type1 = value.getTypeCode(); // Returns 1 (TypeCode.String)
from pip_services3_commons.data import AnyValue

value = AnyValue("123.456")

value1 = value.get_as_integer()                         # Returns 123
value2 = value.get_as_long()                            # Returns 123
value3 = value.get_as_float()                           # Returns 123.456                       

valueB = AnyValue("ABC")
value4 = valueB.get_as_integer_with_default(25)      # Returns 25

value5 = value.get_as_string()                          # Returns '123.456'
value6 = value.get_as_string_with_default("ABC")        # Returns '123.456'

valueB = AnyValue("1")
value7 = valueB.get_as_boolean()                        # Returns True

valueC = AnyValue("abc")
value8 = valueC.get_as_boolean_with_default(False)      # Returns False

type1 = value.get_type_code()                           # Returns TypeCode.String
Not available
Update

This class offers the set_as_object() method to change a value. The following example shows how to use it.

let value = new AnyValue("ABC");
value.setAsObject("CEF");       // Sets value to "CEF"
var value = new AnyValue("ABC");
value.SetAsObject("CEF");       // Sets value to "CEF"
value := data.NewAnyValue("ABC")
value.SetAsObject("CEF") // Sets value to "CEF"
var value = AnyValue('ABC');
value.setAsObject('CEF'); // Sets value to "CEF"
value = AnyValue("ABC")
value.set_as_object("CEF")    # Sets value to "CEF"
Not available
String representation

The method to_string() provides a way to create a string representation of an AnyValue object. The example below shows how to use it.

let value = new AnyValue(123.456);
let value1 = value.toString();    // Returns '123.456'
var value = new AnyValue(123.456);
var value1 = value.ToString();    // Returns '123.456'
value := data.NewAnyValue(123)
value.String() // Returns '123.456'
var value = AnyValue(123.456);
var value1 = value.toString(); // Returns '123.456'
value = AnyValue(123.456)
value1 = value.to_string()    # Returns '123.456'
Not available
Logical operators

The method equals and equals_as_type offer a way to compare two different AnyValue objects. The first compares an object’s value to another specified value. When direct comparison gives a negative result, it tries to compare the values as strings. The second method compares an object’s value to another specified value. When direct comparison gives a negative result, it converts values to a type specified by a type code and compares them again. The following examples show how to use them.

let value = new AnyValue("123.456");
let value2 = value.clone();

let result1 = value.equals(value2);             // Returns True

let result2 = value.equalsAsType(TypeCode.Object, value2);   // Returns True
var value = new AnyValue("123.456");
var value2 = value.Clone();

var result1 = value.Equals(value2);             // Returns True


var result2 = value.EqualsAs<object>(value2);   // Returns True
import (
	"fmt"

	convert "github.com/pip-services3-go/pip-services3-commons-go/convert"
	data "github.com/pip-services3-go/pip-services3-commons-go/data"
)

value := data.NewAnyValue("123.456")
value2 := value.Clone()

result1 := value.Equals(value2) // Returns True

result2 := value.EqualsAsType(convert.Object, value2) // Returns True

var value = AnyValue('123.456');
var value2 = value.clone();

var result1 = value.equals(value2); // Returns True

var result2 = value.equalsAsType(TypeCode.Object, value2); // Returns True
value = AnyValue("123.456")
value2 = value.clone()

result1 = value.equals(value2)                           # Returns True

from pip_services3_commons.convert import TypeCode 
result2 = value.equals_as_type(TypeCode.Object, value2)  # Returns True
Not available

AnyValueArray

This component provides a cross-language implementation of a dynamic array object that can hold values of any type. Each element is referenced by an index value, starting with zero for the first element. For example, the following AnyTypeArray contains a string, an integer, a float, and a date.

let value = new AnyValueArray([ 1, "ABC", 123.45, new Date() ]);
var value = new AnyValueArray(new object[] { 1, "ABC", 123.45, DateTime.Now});
value := data.NewAnyValueArray([]interface{}{1, "ABC", 123.45, time.Now()})
var value = AnyValueArray([1, 'ABC', 123.45, DateTime.now()]);
value = AnyValueArray([1, "ABC", 123.45, date.today()])
Not available
Pre-requisites

To work with this class, we need to import it first. This can be done with the following command:

import { AnyValueArray } from "pip-services3-commons-nodex"
using PipServices3.Commons.Data;
import (
	data "github.com/pip-services3-go/pip-services3-commons-go/data"
)
import 'package:pip_services3_commons/pip_services3_commons.dart';
from pip_services3_commons.data import AnyValueArray
Not available
Create

There are several ways to create an AnyValueArray. First, we can create an instance of the class using a list of values as the input parameter. Second, we can use a string or a list with the methods from_string and from_values respectively. Lastly, we can clone an existing object. The examples below show how to perform each of them.

// Constructor
let value1 = new AnyValueArray([ 1, 2, 3 ]);

// String
let myString = "1.2.3";
let value2 = AnyValueArray.fromString(myString, '.');

// List
let myList = [1, 2, 3];
let value = AnyValueArray.fromValue(myList);

// Cloning
value2 = value.clone();  // Returns value2 as AnyValueArry with values 1,2,3
// Constructor
var value1 = new AnyValueArray(new List<int>() { 1, 2, 3 });

// String
var myString = "1.2.3";
object value2 = AnyValueArray.FromString(myString, '.');

// List
var myList = new List<int>() { 1, 2, 3 };
var value = AnyValueArray.FromValue(myList);

// Cloning
value2 = value.Clone();  // Returns value2 as AnyValueArry with values 1,2,3
// Constructor
value1 := data.NewAnyValueArray([]interface{}{1, 2, 3})

// String
myString := "1.2.3"
value2 := data.NewAnyValueArrayFromString(myString, ".", false)

// List
myList := []int{1, 2, 3}
value := data.NewAnyValueArrayFromValues(myList)

// Cloning
value3 := value.Clone() // Returns value2 as AnyValueArry with values 1,2,3
// Constructor
var value1 = AnyValueArray([1, 2, 3]);

// String
var myString = '1.2.3';
var value2 = AnyValueArray.fromString(myString, '.');

// List
var myList = [1, 2, 3];
var value = AnyValueArray.fromValue(myList);

// Cloning
value2 = value.clone(); // Returns value2 as AnyValueArry with values 1,2,3
# Constructor
value1 = AnyValueArray([1, 2, 3])

# String
my_string = "1.2.3"
value2 = AnyValueArray.from_string(my_string, '.')

# List
my_list = [1, 2, 3]
value = AnyValueArray.from_values(my_list)

# Cloning
value2 = value.clone()    # Returns value2 as AnyValueArry with values 1,2,3
Not available
Contains

This class has the methods contains() and contains_as_type() that can be used to check if a value exists in an AnyValueArray. The first performs a direct comparison, and the second converts to the specified value and then checks if the value exists.

// Find out if it contains a value
let value = new AnyValueArray([ 1, "123.456", "2018-01-01" ]);

let res = value.contains(1); // Returns True

let result = value.containsAsType(TypeCode.Integer, 1);   // Returns True
// Find out if it contains a value
var value = new AnyValueArray(new object[] { 1, "123.456", "2018-01-01" });

var res = value.Contains(1); // Returns True


var result = value.ContainsAs<int>(1);   // Returns True
// Find out if it contains a value
value := data.NewAnyValueArray([]interface{}{1, "123.456", "2018-01-01"})

value.Contains(1) // Returns True
result := value.ContainsAsType(convert.Integer, 1) // Returns True
// Find out if it contains a value
var value = AnyValueArray([1, '123.456', '2018-01-01']);

var res = value.contains(1); // Returns True

var result = value.containsAsType(TypeCode.Integer, 1); // Returns True
# Find out if it contains a value
value = AnyValueArray([1, "123.456", "2018-01-01"])

value.contains(1) # Returns True

from pip_services3_commons.convert import TypeCode
result = value.contains_as_type(TypeCode.Integer, 1)   # Returns True
Not available
Conversion

This class offers several methods to transform the stored values into several well-known formats, such as Boolean, integer, double, float, and more. The examples below show how to use each of them.

import { AnyValueArray, AnyValueMap, TypeCode } from "pip-services3-commons-nodex"

let value = new AnyValueArray([ 1, "123.456", "2018-01-01" ]);

// Get a value for a specified index
let value1 = value.get(0);  // Returns 1, type int

let value2 = value.getAsBoolean(0); // Returns True
let value3 = value.getAsBooleanWithDefault(1, false);   // Returns False
let value4 = value.getAsNullableBoolean(2); // Returns null

let value5 = value.getAsInteger(1); // Returns 123
let value6 = value.getAsIntegerWithDefault(3, 0);   // Returns 0
let value7 = value.getAsNullableInteger(3); // Returns null

let value8 = value.getAsLong(1);    // Returns 123
let value9 = value.getAsLongWithDefault(3, 0);  // Returns 0
let value10 = value.getAsNullableLong(3);   // Returns null

let value11 = value.getAsFloat(1);  // Returns 123.456
let value12 = value.getAsFloatWithDefault(3, 0.0); // Returns 0.0
let value13 = value.getAsNullableFloat(3);  // Returns null

let value14 = value.getAsDouble(1); // Returns 123.456
let value15 = value.getAsDoubleWithDefault(3, 0.0); // Returns 0.0
let value16 = value.getAsNullableDouble(3); // Returns null

let value17 = value.getAsDateTime(2);   // Returns 2018-01-01 00:00:00+00:00

let value18 = value.getAsDateTimeWithDefault(1, new Date());  // Returns (e.g) 2021-11-04

let value19 = value.getAsString(2); // Returns '2018-01-01'
let value20 = value.getAsNullableString(2); // Returns '2018-01-01'
let value21 = value.getAsStringWithDefault(2, "0000-00-00");    // Returns '2018-01-01'

let value22 = value.getAsArray(1);  // Returns ['123.456']
let value23 = value.getAsArrayWithDefault(0, new AnyValueArray([0]));   // Returns [1]
let value24 = value.getAsNullableArray(2);  // Returns ['2018-01-01']

let valueA = new AnyValueArray([1, { "number": "123.456" }, "2018-01-01" ]);
let value25 = valueA.getAsMap(1);   // Returns {'number': '123.456'}
value25 = valueA.getAsMapWithDefault(3, new AnyValueMap({ "key1": 1 })); // Returns {'key1': 1}
let value27 = valueA.getAsNullableMap(3);   // Returns null


let value28 = value.getAsType(TypeCode.DateTime, 2); // Returns 2018-01-01
let value29 = value.getAsTypeWithDefault(TypeCode.DateTime, 1, new Date());    // Returns today date
let value30 = value.getAsNullableType(TypeCode.DateTime, 1); // Returns null


var value = new AnyValueArray(new object[] { 1, "123.456", "2018-01-01" });

// Get a value for a specified index
var value1 = value.Get(0);  // Returns 1, type int

var value2 = value.GetAsBoolean(0); // Returns True
var value3 = value.GetAsBooleanWithDefault(1, false);   // Returns False
var value4 = value.GetAsNullableBoolean(2); // Returns null

var value5 = value.GetAsInteger(1); // Returns 123
var value6 = value.GetAsIntegerWithDefault(2, 0);   // Returns 0
var value7 = value.GetAsNullableInteger(2); // Returns null

var value8 = value.GetAsLong(1);    // Returns 123
var value9 = value.GetAsLongWithDefault(2, 0);  // Returns 0
var value10 = value.GetAsNullableLong(2);   // Returns null

var value11 = value.GetAsFloat(1);  // Returns 123.456
var value12 = value.GetAsFloatWithDefault(2, 0.0f); // Returns 0.0
var value13 = value.GetAsNullableFloat(2);  // Returns null

var value14 = value.GetAsDouble(1); // Returns 123.456
var value15 = value.GetAsDoubleWithDefault(2, 0.0); // Returns 0.0
var value16 = value.GetAsNullableDouble(2); // Returns null

var value17 = value.GetAsDateTime(2);   // Returns 2018-01-01 00:00:00+00:00

var value18 = value.GetAsDateTimeWithDefault(1, DateTime.Now);  // Returns (e.g) 2021-11-04 00:00:00+00:00

var value19 = value.GetAsString(2); // Returns '2018-01-01'
var value20 = value.GetAsNullableString(2); // Returns '2018-01-01'
var value21 = value.GetAsStringWithDefault(2, "0000-00-00");    // Returns '2018-01-01'

var value22 = value.GetAsArray(1);  // Returns ['123.456']
var value23 = value.GetAsArrayWithDefault(0, new AnyValueArray(new List<int> { 0 }));   // Returns [1]
var value24 = value.GetAsNullableArray(2);  // Returns ['2018-01-01']

var valueA = new AnyValueArray(new object[] { 1, new Dictionary<string, string> { { "number", "123.456" } }, "2018-01-01" });
var value25 = valueA.GetAsMap(1);   // Returns {'number': '123.456'}
value25 = valueA.GetAsMapWithDefault(1, new AnyValueMap(new Dictionary<string, int> { { "key1", 1 } })); // Returns {'key1': 1}
var value27 = valueA.GetAsNullableMap(1);   // Returns null


var value28 = value.GetAsType<DateTime>(2); // Returns 2018-01-01 00:00:00+00:00
var value29 = value.GetAsNullableTypeWithDefault<DateTime>(1, DateTime.Now);    // Returns today date
var value30 = value.GetAsNullableType<DateTime>(1); // Returns null

value := data.NewAnyValueArray([]interface{}{1, "123.456", "2018-01-01"})

// Get a value for a specified index
value1 := value.Get(0) // Returns 1, type int

value2 := value.GetAsBoolean(0)                   // Returns True
value3 := value.GetAsBooleanWithDefault(1, false) // Returns False
value4 := value.GetAsNullableBoolean(2)           // Returns nil

value5 := value.GetAsInteger(1)               // Returns 123
value6 := value.GetAsIntegerWithDefault(2, 0) // Returns 0
value7 := value.GetAsNullableInteger(2)       // Returns nil

value8 := value.GetAsLong(1)               // Returns 123
value9 := value.GetAsLongWithDefault(2, 0) // Returns 0
value10 := value.GetAsNullableLong(2)      // Returns nil

value11 := value.GetAsFloat(1)                 // Returns 123.456
value12 := value.GetAsFloatWithDefault(2, 0.0) // Returns 0.0
value13 := value.GetAsNullableFloat(2)         // Returns nil

value14 := value.GetAsDouble(1)                 // Returns 123.456
value15 := value.GetAsDoubleWithDefault(2, 0.0) // Returns 0.0
value16 := value.GetAsNullableDouble(2)         // Returns nil

value17 := value.GetAsDateTime(2) // Returns 01-01-01 00:00:00+00:00

value18 := value.GetAsDateTimeWithDefault(1, time.Now()) // Returns (e.g) 2021-11-04 00:00:00+00:00

value19 := value.GetAsString(2)                          // Returns '2018-01-01'
value20 := value.GetAsNullableString(2)                  // Returns '2018-01-01'
value21 := value.GetAsStringWithDefault(2, "0000-00-00") // Returns '2018-01-01'

value22 := value.GetAsArray(1)                                                     // Returns ['123.456']
value23 := value.GetAsArrayWithDefault(0, data.NewAnyValueArray([]interface{}{0})) // Returns [1]
value24 := value.GetAsNullableArray(2)                                             // Returns ['2018-01-01']

valueA := data.NewAnyValueArray([]interface{}{1, map[string]interface{}{"number": "123.456"}, "2018-01-01"})
value25 := valueA.GetAsMap(1)                                                                   // Returns {'number': '123.456'}
value25 = valueA.GetAsMapWithDefault(1, data.NewAnyValueMap(map[string]interface{}{"key1": 1})) // Returns {'key1': 1}
value27 := valueA.GetAsNullableMap(1)                                                           // Returns nil

value28 := value.GetAsType(convert.DateTime, 2)                        // Returns 2018-01-01 00:00:00+00:00
value29 := value.GetAsTypeWithDefault(convert.DateTime, 1, time.Now()) // Returns today date
value30 := value.GetAsNullableType(convert.DateTime, 1)                // Returns nil
import 'package:pip_services3_commons/pip_services3_commons.dart';

var value = AnyValueArray([1, '123.456', '2018-01-01']);

// Get a value for a specified index
var value1 = value.get(0); // Returns 1, type int

var value2 = value.getAsBoolean(0); // Returns True
var value3 = value.getAsBooleanWithDefault(1, false); // Returns False
var value4 = value.getAsNullableBoolean(2); // Returns null

var value5 = value.getAsInteger(1); // Returns 123
var value6 = value.getAsIntegerWithDefault(2, 0); // Returns 0
var value7 = value.getAsNullableInteger(2); // Returns null

var value8 = value.getAsLong(1); // Returns 123
var value9 = value.getAsLongWithDefault(2, 0); // Returns 0
var value10 = value.getAsNullableLong(2); // Returns null

var value11 = value.getAsFloat(1); // Returns 123.456
var value12 = value.getAsFloatWithDefault(2, 0.0); // Returns 0.0
var value13 = value.getAsNullableFloat(2); // Returns null

var value14 = value.getAsDouble(1); // Returns 123.456
var value15 = value.getAsDoubleWithDefault(2, 0.0); // Returns 0.0
var value16 = value.getAsNullableDouble(2); // Returns null

var value17 = value.getAsDateTime(2).toLocal(); // Returns 2018-01-01 00:00:00+00:00

var value18 = value.getAsDateTimeWithDefault(1, DateTime.now()); // Returns (e.g) 2021-11-04

var value19 = value.getAsString(2); // Returns '2018-01-01'
var value20 = value.getAsNullableString(2); // Returns '2018-01-01'
var value21 = value.getAsStringWithDefault(2, '0000-00-00'); // Returns '2018-01-01'

var value22 = value.getAsArray(1); // Returns ['123.456']
var value23 = value.getAsArrayWithDefault(0, AnyValueArray([0])); // Returns [1]
var value24 = value.getAsNullableArray(2); // Returns ['2018-01-01']

var valueA = AnyValueArray([
  1,
  {'number': '123.456'},
  '2018-01-01'
]);

var value25 = valueA.getAsMap(1); // Returns {'number': '123.456'}
value25 = valueA.getAsMapWithDefault(2, AnyValueMap({'key1': 1})); // Returns {'key1': 1}

var value27 = valueA.getAsNullableMap(2); // Returns null

var value28 = value.getAsType(TypeCode.DateTime, 2).toLocal(); // Returns 2018-01-01
var value29 = value.getAsTypeWithDefault(TypeCode.DateTime, 1, DateTime.now()); // Returns today date
var value30 = value.getAsNullableType(TypeCode.DateTime, 1); // Returns null

value = AnyValueArray([1, "123.456", "2018-01-01"])

# Get a value for a specified index
value1 = value.get(0)                                   # Returns 1, type int

value2 = value.get_as_boolean(0)                        # Returns True
value3 = value.get_as_boolean_with_default(1, False)     # Returns False
value4 = value.get_as_nullable_boolean(2)               # Returns None

value5 = value.get_as_integer(1)                        # Returns 123
value6 = value.get_as_integer_with_default(3, 0)        # Returns 0
value7 = value.get_as_nullable_integer(3)               # Returns None

value8 = value.get_as_long(1)                           # Returns 123
value9 = value.get_as_long_with_default(3, 0)           # Returns 0
value10 = value.get_as_nullable_long(3)                 # Returns None

value11 = value.get_as_float(1)                         # Returns 123.456
value12 = value.get_as_float_with_default(3, 0.0)       # Returns 0.0
value13 = value.get_as_nullable_float(3)                # Returns None

value14 = value.get_as_double(1)                        # Returns 123.456
value15 = value.get_as_double_with_default(3, 0.0)      # Returns 0.0
value16 = value.get_as_nullable_double(3)               # Returns None

value17 = value.get_as_datetime(2)                      # Returns 2018-01-01 00:00:00+00:00
from datetime import date
value18 = value.get_as_datetime_with_default(1, date.today())  # Returns (e.g) 2021-11-04 00:00:00+00:00

value19 = value.get_as_string(2)                        # Returns '2018-01-01'
value20 = value.get_as_nullable_string(2)               # Returns '2018-01-01'
value21 = value.get_as_string_with_default(2,'0000-00-00')       # Returns '2018-01-01'

value22 = value.get_as_array(1)                         # Returns ['123.456']
value23 = value.get_as_array_with_default(0, AnyValueArray([0]))       # Returns [1]
value24 = value.get_as_nullable_array(2)                # Returns ['2018-01-01']

valueA = AnyValueArray([1, {'number': "123.456"}, "2018-01-01"])
value25 = valueA.get_as_map(1)                           # Returns {'number': '123.456'}
value25 = valueA.get_as_map_with_default(3, AnyValueMap({'key1': 1})) # Returns {'key1': 1}
value27 = valueA.get_as_nullable_map(3)                  # Returns None

from pip_services3_commons.convert import TypeCode 
value28 = value.get_as_type(TypeCode.DateTime,2)        # Returns 2018-01-01 00:00:00+00:00
value29 = value.get_as_type_with_default(TypeCode.DateTime, 1, date.today())      # Returns today date
value30 = value.get_as_nullable_type(TypeCode.DateTime,1)                       # Returns None
Not available
Update

We can either append a value or a list of values to an AnyValueArray with the append method or change the value of any element with the put method. The following examples show how to use them.

// Replace a value
let value = AnyValueArray([1, 2, 3]);
value.put(0,"ABC");    // Returns ABC,2,3

// Append a value
let myList = [1,3,4];
value.append(my_list);  // Returns ABC,2,3,1,3,4
// Replace a value
var value = new AnyValueArray(new List<int> { 1, 2, 3 });
value.Set(0, "ABC");   // Returns ABC,2,3

// Append a value
var myList = new List<int>{1, 3, 4};
value.Add(myList);  // Returns ABC,2,3,1,3,4


// Replace a value
value := data.NewAnyValueArray([]interface{}{1, 2, 3})
value.Put(0, "ABC") // Returns ABC,2,3

// Append a value
myList := []interface{}{1, 3, 4}
value.Append(myList) // Returns ABC,2,3,1,3,4

// Replace a value
var value = AnyValueArray([1, 2, 3]);
value.put(0, 'ABC'); // Returns ABC,2,3

// Append a value
var myList = [1, 3, 4];
value.append(myList); // Returns ABC,2,3,1,3,4
# Replace a value
value = AnyValueArray([1, 2, 3])
value.put(0,"ABC")    # Returns ABC,2,3

# Append a value
my_list = [1,3,4]
value.append(my_list)  # Returns ABC,2,3,1,3,4

Not available
Delete

To delete an element included in an AnyValueArray, we can use the remove method. This method asks the index of the element to be removed as input parameter. The code below shows how to use it.

let value = new AnyValueArray([ 1, "123.456", "2018-01-01" ]);
value.remove(0);    // Returns 123.456,2018-01-01
var value = new AnyValueArray(new object[] { 1, "123.456", "2018-01-01" });
value.Remove(0);    // Returns 123.456,2018-01-01
value := data.NewAnyValueArray([]interface{}{1, "123.456", "2018-01-01"})
value.Remove(0) // Returns 123.456,2018-01-01
var value = AnyValueArray([1, '123.456', '2018-01-01']);
value.remove(0); // Returns 123.456,2018-01-01
value = AnyValueArray([1, "123.456", "2018-01-01"])
value.remove(0)    # Returns 123.456,2018-01-01
Not available

AnyValueMap

The AnyValueMap class provides a cross-language implementation of a dynamic map (dictionary) object that can hold values of any type. For example, the following map contains an integer, a float, a string, and a date.

let value = new AnyValueMap({
    "key1": 1,
    "key2": 123.456,
    "key3": "ABC",
    "key4": new Date()
});

var value = new AnyValueMap(new Dictionary<object, object>{
    { "key1", 1 },
    {"key2", 123.456 },
    {"key3", "ABC" },
    {"key4", DateTime.Now }
});

value := data.NewAnyValueMap(map[string]interface{}{"key1": 1, "key2": 123.456, "key3": "ABC", "key4": time.Now()})
var value = AnyValueMap({'key1': 1, 'key2': 123.456, 'key3': 'ABC', 'key4': DateTime.now()});

value = AnyValueMap({ 'key1': 1, 'key2': 123.456, 'key3': "ABC", 'key4': date.today() })
Not available
Pre-requisites

To use this component, we need to import its class first. The following code shows how to do this.

import { AnyValueMap } from "pip-services3-commons-nodex"
using PipServices3.Commons.Data;
import (
	data "github.com/pip-services3-go/pip-services3-commons-go/data"
)
import 'package:pip_services3_commons/pip_services3_commons.dart';
from pip_services3_commons.data import AnyValueMap
Not available
Create

There are several ways to create an AnyValueMap object. It can be created by defining a new instance with the constructor, from a list of maps or tuples, or by cloning. The examples below show how to perform these operations.

// Constructor
let value = new AnyValueMap({
    "key1": 1,
    "key2": "123.456",
    "key3": "2018-01-01"
}); // Returns {"key1": 1, "key2": "123.456", "key3": "2018-01-01"}

// Cloning
let value2 = value.clone();   // Returns {"key1": 1, "key2": "123.456", "key3": "2018-01-01"}

// Maps
let myMap1 = new AnyValueMap({
    "key1": 1 ,
    "key2": "123.456" ,
    "key3": "2018-01-01" 
});

let myMap2 = {
    "key4": 2,
    "key5": 3,
    "key6": 4,
};

value = AnyValueMap.fromMaps(myMap1, myMap2);    // Returns {"key1": 1,"key2": "123.456","key3": "2018-01-01","key4": 2,"key5": 3,"key6": 4} 

// Tuples
value = AnyValueMap.fromTuples("key1", 1, "key2", "123.456", "key3", "2018-01-01");     // Returns {"key1": 1, "key2": "123.456", "key3": "2018-01-01"}

// Array of tuples
let myTuple = [ "key1", 1, "key2", "123.456", "key3", "2018-01-01" ];
value = AnyValueMap.fromTuplesArray(myTuple);  // Returns {"key1": 1, "key2": "123.456", "key3": "2018-01-01"}

// Values
let myValue = [1,2];
value = AnyValueMap.fromValue(myValue);       // Returns {"0": 1, "1": 2}

// Constructor
var value = new AnyValueMap(new Dictionary<object, object> {
    { "key1", 1 },
    {"key2", "123.456" },
    {"key3", "2018-01-01" }
});    // Returns {"key1": 1, "key2": "123.456", "key3": "2018-01-01"}

// Cloning
var value2 = value.Clone();   // Returns {"key1": 1, "key2": "123.456", "key3": "2018-01-01"}

// Maps
var myMap1 = new AnyValueMap(new Dictionary<object, object> {
    { "key1", 1 },
    {"key2", "123.456" },
    {"key3", "2018-01-01" }
});

var myMap2 = new Dictionary<object, object> {
    { "key4", 2},
    { "key5", 3},
    {"key6", 4 }
};

value = AnyValueMap.FromMaps(myMap1, myMap2);    // Returns {"key1": 1,"key2": "123.456","key3": "2018-01-01","key4": 2,"key5": 3,"key6": 4} 

// Tuples
value = AnyValueMap.FromTuples("key1", 1, "key2", "123.456", "key3", "2018-01-01");     // Returns {"key1": 1, "key2": "123.456", "key3": "2018-01-01"}

// Array of tuples
var myTuple = new object[] { "key1", 1, "key2", "123.456", "key3", "2018-01-01" };
value = AnyValueMap.FromTuplesArray(myTuple);  // Returns {"key1": 1, "key2": "123.456", "key3": "2018-01-01"}

// Values
var myValue = new List<int> { 1, 2 };
value = AnyValueMap.FromValue(myValue);       // Returns {"0": 1, "1": 2}

// Constructor
value := data.NewAnyValueMap(map[string]interface{}{"key1": 1, "key2": "123.456", "key3": "2018-01-01"}) // Returns{"key1": 1, "key2": "123.456", "key3": "2018-01-01"}

// Cloning
value2 := value.Clone() // Returns {"key1": 1, "key2": "123.456", "key3": "2018-01-01"}
	
// Maps
myMap1 := map[string]interface{}{"key1": 1, "key2": "123.456", "key3": "2018-01-01"}
myMap2 := map[string]interface{}{"key4": 2, "key5": 3, "key6": 4}

value = data.NewAnyValueMapFromMaps(myMap1, myMap2) // Returns {"key1": 1,"key2": "123.456","key3": "2018-01-01","key4": 2,"key5": 3,"key6": 4}

// Tuples
value = data.NewAnyValueMapFromTuples("key1", 1, "key2", "123.456", "key3", "2018-01-01") // Returns {"key1": 1, "key2": "123.456", "key3": "2018-01-01"}

// Array of tuples
myTuple := []interface{}{"key1", 1, "key2", "123.456", "key3", "2018-01-01"}
value = data.NewAnyValueMapFromTuplesArray(myTuple) // Returns {"key1": 1, "key2": "123.456", "key3": "2018-01-01"}

// Values
myValue := []int{1, 2}
value = data.NewAnyValueMapFromValue(myValue) // Returns {"0": 1, "1": 2}
// Constructor
var value = AnyValueMap({
  'key1': 1,
  'key2': '123.456',
  'key3': '2018-01-01'
}); // Returns {"key1": 1, "key2": "123.456", "key3": "2018-01-01"}

// Cloning
var value2 = value.clone(); // Returns {"key1": 1, "key2": "123.456", "key3": "2018-01-01"}

  // Maps
  var myMap1 = AnyValueMap({'key1': 1, 'key2': '123.456', 'key3': '2018-01-01'});

var myMap2 = {
  'key4': 2,
  'key5': 3,
  'key6': 4,
};

value = AnyValueMap.fromMaps([
  myMap1,
  myMap2
]); // Returns {"key1": 1,"key2": "123.456","key3": "2018-01-01","key4": 2,"key5": 3,"key6": 4}

// Tuples
value = AnyValueMap.fromTuples([
  'key1',
  1,
  'key2',
  '123.456',
  'key3',
  '2018-01-01'
]); // Returns {"key1": 1, "key2": "123.456", "key3": "2018-01-01"}

// Array of tuples
var myTuple = ['key1', 1, 'key2', '123.456', 'key3', '2018-01-01'];
value = AnyValueMap.fromTuplesArray(myTuple); // Returns {"key1": 1, "key2": "123.456", "key3": "2018-01-01"}

// Values
var myValue = [1, 2];
value = AnyValueMap.fromValue(myValue); // Returns {"0": 1, "1": 2}

# Constructor
value = AnyValueMap({ 'key1': 1, 'key2': "123.456", 'key3': "2018-01-01" })    # Returns {'key1': 1, 'key2': '123.456', 'key3': '2018-01-01'}

# Cloning
value2 = value.clone()    # Returns {'key1': 1, 'key2': '123.456', 'key3': '2018-01-01'}

# Maps
my_map1 = { 'key1': 1, 'key2': "123.456", 'key3': "2018-01-01" }
my_map2  = {'key4': 2, 'key5': 3, 'key6': 4}

list_of_maps = [my_map1, my_map2]
value = AnyValueMap.from_maps(*list_of_maps)     # Returns {'key1': 1,'key2': '123.456','key3': '2018-01-01','key4': 2,'key5': 3,'key6': 4} 

# Tuples
my_tuple2 = ['key1', 1, 'key2', '123.456', 'key3', "2018-01-01"]
value = AnyValueMap.from_tuples(*my_tuple2)      # Returns {'key1': 1, 'key2': '123.456', 'key3': '2018-01-01'}

# Array of tuples
my_tuple = ['key1', 1, 'key2', '123.456', 'key3', "2018-01-01"]
value = AnyValueMap.from_tuples_array(my_tuple)   # Returns {'key1': 1, 'key2': '123.456', 'key3': '2018-01-01'}

# Values
my_value = [1,2]  
value = AnyValueMap.from_value(my_value)         # Returns {'0': 1, '1': 2}
Not available
Conversion

This class offers several methods to extract the value of an element specified by its key in different known formats such as Boolean, integer, float, and more. The following examples show how to use them.

let value = new AnyValueMap({
    "key1": 1,
    "key2": "123.456",
    "key3": "2018-01-01",
    "key4": "word"
});

let value1 = value.getAsBoolean("key1");   // Returns: true
let value2 = value.getAsInteger("key2");   // Returns: 123
let value3 = value.getAsIntegerWithDefault("key4", 0);   // Returns 0
let value4 = value.getAsFloat("key2");     // Returns: 123.456
let value5 = value.getAsDateTime("key3");  // Returns new 2018-0-1
let valueA = new AnyValueMap({ 
    "key1": 1,
    "key2":  { "key": "123.456" },
    "key3": "2018-01-01" 
}); // redact

let value6 = valueA.getAsMap("key2");      // Returns {'key': '123.456'}
let value7 = value.getAsNullableDateTime("key2");     // Returns null
let value8 = value.getAsNullableDateTime("key3");     // Returns 2018-0-1
let value9 = value.getAsString("key1");    // Returns '1'
let value10 = value.getAsObject();                     // Returns {'key1': 1, 'key2': '123.456', 'key3': '2018-01-01'}

let value11 = value.getAsType(TypeCode.String, "key1");     // Returns '1'
let value12 = value.getAsValue("key1");

var value = new AnyValueMap(new Dictionary<object, object>{
    {"key1", 1 },
    {"key2", "123.456" },
    { "key3", "2018-01-01"}
});

var value1 = value.GetAsBoolean("key1");   // Returns: true
var value2 = value.GetAsInteger("key2");   // Returns: 123
var value3 = value.GetAsIntegerWithDefault("key3", 0);   // Returns 0
var value4 = value.GetAsFloat("key2");     // Returns: 123.456
var value5 = value.GetAsDateTime("key3");  // Returns new 2018-0-1
var valueA = new AnyValueMap(new Dictionary<object, object>{ 
    { "key1", 1}, 
    { "key2", new Dictionary<object, object>{ { "key", "123.456" } } },
    { "key3", "2018-01-01" }
}); // redact
var value6 = valueA.GetAsMap("key2");      // Returns {'key': '123.456'}
var value7 = value.GetAsNullableDateTime("key2");     // Returns null
var value8 = value.GetAsNullableDateTime("key3");     // Returns 2018-0-1
var value9 = value.GetAsString("key1");    // Returns '1'
var value10 = value.GetAsObject();                     // Returns {'key1': 1, 'key2': '123.456', 'key3': '2018-01-01'}

var value11 = value.GetAsType<string>("key1");     // Returns '1'
var value12 = value.GetAsValue("key1");

value = AnyValueMap({ 'key1': 1, 'key2': "123.456", 'key3': "2018-01-01" })

value1 = value.get_as_boolean("key1")   # Returns: true
value2 = value.get_as_integer("key2")   # Returns: 123
value3 = value.get_as_integer_with_default("key3", 0)   # Returns 0
value4 = value.get_as_float("key2")     # Returns: 123.456
value5 = value.get_as_datetime("key3")  # Returns new Date(2018,0,1)
value9 = value.get_as_string("key1")    # Returns '1'
valueA = AnyValueMap({'key1': 1, 'key2': {'key': "123.456"}, 'key3': "2018-01-01"}) # redact
value6 = valueA.get_as_map("key2")      # Returns {'key': '123.456'}
value7 = value.get_as_nullable_datetime("key2")     # Returns None
value8 = value.get_as_nullable_datetime("key3")     # Returns new Date(2018,0,1)
value10 = value.get_as_object()                     # Returns {'key1': 1, 'key2': '123.456', 'key3': '2018-01-01'}

from pip_services3_commons.convert import TypeCode
value11 = value.get_as_type(TypeCode.String, 'key1')     # Returns '1'
value12 = value.get_as_value('key1')
var value = AnyValueMap({'key1': 1, 'key2': '123.456', 'key3': '2018-01-01', 'key4': 'word'});

var value1 = value.getAsBoolean('key1'); // Returns: true
var value2 = value.getAsInteger('key2'); // Returns: 123
var value3 = value.getAsIntegerWithDefault('key4', 0); // Returns 0
var value4 = value.getAsFloat('key2'); // Returns: 123.456
var value5 = value.getAsDateTime('key3').toLocal(); // Returns new 2018-0-1
var valueA = AnyValueMap({
  'key1': 1,
  'key2': {'key': '123.456'},
  'key3': '2018-01-01'
}); // redact

var value6 = valueA.getAsMap('key2'); // Returns {'key': '123.456'}
var value7 = value.getAsNullableDateTime('key2'); // Returns null
var value8 = value.getAsNullableDateTime('key3')?.toLocal(); // Returns 2018-0-1
var value9 = value.getAsString('key1'); // Returns '1'
var value10 = value.getAsObject(); // Returns {'key1': 1, 'key2': '123.456', 'key3': '2018-01-01'}

var value11 = value.getAsType(TypeCode.String, 'key1'); // Returns '1'
var value12 = value.getAsValue('key1');
value := data.NewAnyValueMap(map[string]interface{}{"key1": 1, "key2": "123.456", "key3": "2018-01-01"})

value1 := value.GetAsBoolean("key1")               // Returns: true
value2 := value.GetAsInteger("key2")               // Returns: 123
value3 := value.GetAsIntegerWithDefault("key3", 0) // Returns 0
value4 := value.GetAsFloat("key2")                 // Returns: 123.456
value5 := value.GetAsDateTime("key3")              // Returns 0001-01-01
valueA := data.NewAnyValueMap(map[string]interface{}{"key1": 1, "key2": map[string]string{"key": "123.456"}, "key3": "2018-01-01"})
value6 := valueA.GetAsMap("key2")                  // Returns {"key": "123.456"}
value7 := value.GetAsNullableDateTime("key2")      // Returns nil
value8 := value.GetAsNullableDateTime("key3")      // Returns nil
value9 := value.GetAsString("key1")                // Returns "1"
value10 := value.GetAsType(convert.String, "key1") // Returns "1"
value11 := value.GetAsValue("key1")
Not available
Update

The method set_as_object() allows us to change the value of an element according to its key. The example below shows how to do this.

let value = new AnyValueMap({
    "key1": 1 ,
    "key2": "123.456",
    "key3": "2018-01-01" 
});

value.setAsObject("key1", 2);          // Returns {"key1": 2, "key2": "123.456", "key3": "2018-01-01"}

var value = new AnyValueMap(new Dictionary<object, object>{
    {"key1", 1 },
    { "key2", "123.456"},
    { "key3", "2018-01-01"} });
value.SetAsObject("key1", 2);          // Returns {"key1": 2, "key2": "123.456", "key3": "2018-01-01"}

value := data.NewAnyValueMap(map[string]interface{}{"key1": 1, "key2": "123.456", "key3": "2018-01-01"})
value.SetAsObject("key1", 2) // Returns {"key1": 2, "key2": "123.456", "key3": "2018-01-01"}
var value = AnyValueMap({'key1': 1, 'key2': '123.456', 'key3': '2018-01-01'});

value.setAsObject('key1',2); // Returns {"key1": 2, "key2": "123.456", "key3": "2018-01-01"}

value = AnyValueMap({ 'key1': 1, 'key2': "123.456", 'key3': "2018-01-01" })
value.set_as_object('key1', 2)           # Returns {'key1': 2, 'key2': '123.456', 'key3': '2018-01-01'}
Not available
Delete

To remove an element, we can use the remove method. This method accepts the key of a value as input. The example below shows how to use it.

var value = new AnyValueMap({
    "key1": 1,
    "key2": "123.456",
    "key3": "2018-01-01" 
});
value.remove("key1");        // Returns value = {'key2': '123.456', 'key3': '2018-01-01'}

var value = new AnyValueMap(new Dictionary<object, object>{
    {"key1", 1 },
    { "key2", "123.456"},
    { "key3", "2018-01-01"} });
value.Remove("key1");        // Returns value = {'key2': '123.456', 'key3': '2018-01-01'}

value := data.NewAnyValueMap(map[string]interface{}{"key1": 1, "key2": "123.456", "key3": "2018-01-01"})
value.Remove("key1") /// Returns value = {"key2": "123.456", "key3": "2018-01-01"}
var value = AnyValueMap({'key1': 1, 'key2': '123.456', 'key3': '2018-01-01'});

value.remove('key1'); // Returns value = {'key2': '123.456', 'key3': '2018-01-01'}

value = AnyValueMap({ 'key1': 1, 'key2': "123.456", 'key3': "2018-01-01" })
value.remove('key1')     # Returns value = {'key2': '123.456', 'key3': '2018-01-01'}
Not available

Wrapping up

In this tutorial, we have seen how to use the three dynamic data types available in Pip.Services namely, AnyValue, AnyValueArray, and AnyValueMap.

AnyValue offers a dynamic type for single values. AnyValueArray is a dynamic type for arrays and AnyValueMap gives us a dynamic type for maps.

We have also seen examples of all the methods to create, extract, modify and delete values or elements that these classes have.