Value Types

Overview

Robot Raconteur passes “Value Types” between clients and services by value. The values are “serialized” to a binary format that can be transmitted over a network. The values are then “deserialized” back into the original data type. The serialization and deserialization process is handled transparently by the Robot Raconteur library. Because Robot Raconteur supports multiple programming languages, the value types are defined using Robot Raconteur “Service Definitions,” which provide a common language-independent format for defining data types. The Value Types are carefully designed to support robotics and automation applications.

The following data types are supported by Robot Raconteur:

bool - A boolean value that can be either true or false. * Arrays and multidimensional arrays of booleans.
Numeric types including uint8, int8, uint16, int16, uint32, int32, uint64, int64, single, double, csingle, and cdouble. * Arrays and multidimensional arrays of numeric types.
string - A string of characters.
struct - A structure that contains a collection of fields.
pod - A “Plain Old Data” structure that contains a collection of fields that are stored in contiguous memory. * Arrays and multidimensional arrays of POD types.
namedarray - A structure that contains a collection of fields that are stored as a union between a structure and a numeric array in contiguous memory. * Arrays and multidimensional arrays of namedarray types.
Collection types including list, map{int32}, and map{string}. * Any of the above types can be used as the value type in a collection type.

The struct, pod, and namedarray types are defined using the Robot Raconteur “Service Definitions” format.

Object “members” are used to interact with services and pass data between clients and services. The examples on this page use property types to pass data between clients and services. The value types can all be used with all member types.

The example service definition experimental.value_types is used for the examples on this page. The service definition is shown below:

service experimental.value_types

stdver 0.10

# Example vector namedarray. Note that all fields must
# have the same underlying numeric type
namedarray MyVector3
    field double x
    field double y
    field double z
end

namedarray MyQuaternion
    field double w
    field double x
    field double y
    field double z
end

# Example pose namedarray using composition of other namedarrays.
# All underlying fields must have the same numeric type.
namedarray MyPose
    field MyQuaternion orientation
    field MyVector3 position
end

# Pod example. Only numeric types, other pods, and namedarrays can
# be used in a pod. All arrays must have a fixed or maximum length.
# Multidimarrays must be fixed. Pods have a fixed maximum binary
# size to fit in contiguous memory. Pods do not
# have to have the same underlying numeric type for all the
# fields.
pod MyPod
    field double a
    field int32 b
    field uint8[4] c
    field uint8[4-] d
    field uint16[2,3] e
    field MyVector3 f
end

# Structure examples.
struct MyStructure
    # struct fields can be any value type
    field double a
    field uint32[2] b
    field string c
    field string{list} d
end

# This object contains examples of many value types. The names of the fields are
# arbitrary. See the standard service definitions for examples of more
# common naming conventions.
object ValueTypesExample
    # Examples of scalar numeric types
    property double a_double
    property int32 b_int
    property uint8 c_byte
    property cdouble d_cdouble
    property bool e_bool
    property int32 meaning_of_life [readonly]

    # Examples of numeric arrays. Any numeric array type
    # can be used
    property double[] a_double_array
    property double[3] a_double_array_fixed
    property double[6-] a_double_array_maxlen
    property double[3,2] a_double_marray_fixed
    property double[*] a_double_marray
    property uint8[] c_byte_array

    property string f_string

    # Examples using namedarray
    property MyVector3 g_vector
    property MyVector3[] g_vector_array
    property MyQuaternion h_quaternion
    property MyPose i_pose

    # Examples using pods
    property MyPod j_pod
    property MyPod[] j_pod_array

    # Examples using structures
    property MyStructure k_struct

    # Container examples
    # Containers can be int32 key maps, string key maps, or lists
    # All types can be stored in containers, but containers cannot
    # directly contain other containers. For example
    # string{list} is allowed, but string{list}{list} is not.
    property double{int32} l_double_map
    property double[]{string} l_double_array_map
    property string{list} m_string_list
    property string{int32} m_string_map_int32
    property string{string} m_string_map_string
    property MyVector3{int32} n_vector_map
    property MyStructure{list} o_struct_list

    # varvalue examples
    property varvalue p_varvalue_double_array
    property varvalue q_varvalue_string
    property varvalue r_varvalue_struct
    # varvalue{string} is a string keyed map of varvalues
    # It is frequently used for "extended" fields
    # to allow for forward compatibility
    property varvalue{string} s_varvalue_map2

    # Null examples
    property MyStructure t_struct_null
end

Numeric Types

Robot Raconteur supports numeric types including uint8, int8, uint16, int16, uint32, int32, uint64, int64, single, double, csingle, and cdouble. For the purpose of this section, bool is also considered a numeric type. Scalar numbers are converted to the built-in numeric types in the client programming language. Numeric types can also be stored in arrays and multidimensional arrays.

The following members from the experimental.value_types.ValueTypesExample object are used in the examples for numeric types:

    # Examples of scalar numeric types
    property double a_double
    property int32 b_int
    property uint8 c_byte
    property cdouble d_cdouble
    property bool e_bool
    property int32 meaning_of_life [readonly]

    # Examples of numeric arrays. Any numeric array type
    # can be used
    property double[] a_double_array
    property double[3] a_double_array_fixed
    property double[6-] a_double_array_maxlen
    property double[3,2] a_double_marray_fixed
    property double[*] a_double_marray
    property uint8[] c_byte_array

The examples below show how to use the numeric types in Python, MATLAB, LabView, C#, and C++.

# numeric_value_types.py - Example of using numeric value types

from RobotRaconteur.Client import *
import numpy as np

c = RRN.ConnectService('rr+tcp://localhost:53223?service=values_example')

# Scalar numbers
# property double a_double
a_double_read = c.a_double
print(a_double_read)
# assert is used for the rest of the example property read operations
# to demonstrate the expected values.
assert (c.a_double == 5.78)
c.a_double = 49.3
# property int32 b_int
assert (c.b_int == 4557)
c.b_int = 359
# property uint8 c_byte
assert (c.c_byte == 0x1A)
c.c_byte = 31
# property cdouble d_cdouble
assert (c.d_cdouble == 23.7 + 1j * 5.3)
c.d_cdouble = 1.2 + 3.4j
# property bool e_bool
assert (c.e_bool == True)
c.e_bool = False
# property int32 meaning_of_life [readonly]
assert (c.meaning_of_life == 42)

# Numeric Arrays
# Note the use of `dtype` parameter when creating arrays. This must match the
# type specified in the service definition.
# property double[] a_double_array
np.testing.assert_allclose(c.a_double_array, [0.016, 0.226])
c.a_double_array = np.array([0.582, 0.288, 0.09, 0.213, 0.98], dtype=np.float64)
# property double[3] a_double_array_fixed
np.testing.assert_allclose(c.a_double_array_fixed, [0.13, 0.27, 0.15])
c.a_double_array_fixed = np.array([0.21, 0.12, 0.39], dtype=np.float64)
# property double[6-] a_double_array_maxlen
np.testing.assert_allclose(c.a_double_array_maxlen, [0.7, 0.16, 0.16, 0.05, 0.61, 0.9])
c.a_double_array_maxlen = np.array([0.035, 0.4], dtype=np.float64)
# property double[3,2] a_double_marray_fixed
np.testing.assert_allclose(c.a_double_marray_fixed, [[0.29, 0.66], [0.41, 0.6], [0.4, 0.2]])
c.a_double_marray_fixed = np.array([[0.3, 0.6], [0.4, 0.6], [0.5, 0.2]], dtype=np.float64)
# property double[*] a_double_marray
np.testing.assert_allclose(c.a_double_marray, [[0.72, 0.4], [0.05, 0.07]])
c.a_double_marray = np.array([[0.3], [0.01]], dtype=np.float64)
# property uint8[] c_byte_array
np.testing.assert_array_equal(c.c_byte_array, [0x1A, 0x2B])
c.c_byte_array = np.array([0x3C, 0x4D, 0x5E, 0x6F, 0x70], dtype=np.uint8)

% numeric_value_types.m - Example of using numeric value types

c = RobotRaconteur.ConnectService('rr+tcp://localhost:53223?service=values_example');

% Scalar numbers
% property double a_double
a_double_read = c.a_double;
disp(a_double_read);
% assert is used for the rest of the example property read operations
% to demonstrate the expected values.
assert(c.a_double == 5.78);
c.a_double = 49.3;
% property int32 b_int
assert (c.b_int == 4557)
c.b_int = int32(359);
% property uint8 c_byte
assert (c.c_byte == 0x1A)
c.c_byte = uint8(31);
% property cdouble d_cdouble
assert (c.d_cdouble == 23.7 + 5.3i)
c.d_cdouble = 1.2 + 3.4i;
% property bool e_bool
assert (c.e_bool == true)
c.e_bool = false;
% property int32 meaning_of_life [readonly]
assert (c.meaning_of_life == 42)

% Numeric Arrays
% property double[] a_double_array
assert(isequal(c.a_double_array, [0.016, 0.226]'));
c.a_double_array = [0.582, 0.288, 0.09, 0.213, 0.98]';
% property double[3] a_double_array_fixed
assert(isequal(c.a_double_array_fixed, [0.13, 0.27, 0.15]'));
c.a_double_array_fixed = [0.21,0.12, 0.39]';
% property double[6-] a_double_array_maxlen
assert(isequal(c.a_double_array_maxlen, [0.7, 0.16, 0.16, 0.05, 0.61, 0.9]'));
c.a_double_array_maxlen = [0.035, 0.4]';
% property double[3,2] a_double_marray_fixed
assert(isequal(c.a_double_marray_fixed, [0.29, 0.66; 0.41, 0.6; 0.4, 0.2]));
c.a_double_marray_fixed = [0.3, 0.6; 0.4, 0.6; 0.5, 0.2];
% property double[*] a_double_marray
assert(isequal(c.a_double_marray, [0.72, 0.4; 0.05, 0.07]));
c.a_double_marray = [0.3; 0.01];
% property uint8[] c_byte_array
assert(isequal(c.c_byte_array, [0x1A, 0x2B]'));
c.c_byte_array = uint8([0x3C, 0x4D, 0x5E, 0x6F, 0x70]');

RobotRaconteur.DisconnectService(c);

// numeric_value_types.cs - Example of using numeric value types

using RobotRaconteur;
using System;
using System.Diagnostics;
using System.Linq;

using (var node_setup = new ClientNodeSetup(args))
{

    var c = (experimental.value_types.ValueTypesExample)RobotRaconteurNode.s.ConnectService(
        "rr+tcp://localhost:53223?service=values_example");

    // Scalar numbers
    // property double a_double
    double a_double_read = c.a_double;
    Console.WriteLine(a_double_read);
    // Debug.Assert is used for the rest of the example property read operations
    // to demonstrate the expected values.
    Debug.Assert(c.a_double == 5.78);
    c.a_double = 49.3;
    // property int32 b_int
    Debug.Assert(c.b_int == 4557);
    c.b_int = (int)359;
    // property uint8 c_byte
    Debug.Assert(c.c_byte == 0x1A);
    c.c_byte = (byte)31;
    // property cdouble d_cdouble
    Debug.Assert(c.d_cdouble == new CDouble(23.7, 5.3));
    c.d_cdouble = new CDouble(1.2, 3.4);
    // property bool e_bool
    Debug.Assert(c.e_bool == true);
    c.e_bool = false;
    // property int32 meaning_of_life [readonly]
    Debug.Assert(c.meaning_of_life == 42);

    // Numeric Arrays
    // property double[] a_double_array
    Debug.Assert(Enumerable.SequenceEqual(c.a_double_array, new double[] { 0.016, 0.226 }));
    c.a_double_array = new double[] { 0.582, 0.288, 0.09, 0.213, 0.98 };
    // property double[3] a_double_array_fixed
    Debug.Assert(Enumerable.SequenceEqual(c.a_double_array_fixed, new double[] { 0.13, 0.27, 0.15 }));
    c.a_double_array_fixed = new double[] { 0.21, 0.12, 0.39 };
    // % property double[6-] a_double_array_maxlen
    Debug.Assert(Enumerable.SequenceEqual(c.a_double_array_maxlen, new double[] { 0.7, 0.16, 0.16, 0.05, 0.61, 0.9 }));
    c.a_double_array_maxlen = new double[] { 0.035, 0.4 };
    // property double[3,2] a_double_marray_fixed
    var a_double_marray_fixed_read = c.a_double_marray_fixed;
    Debug.Assert(Enumerable.SequenceEqual(a_double_marray_fixed_read.Dims, new uint[] { 3, 2 }));
    Debug.Assert(Enumerable.SequenceEqual((double[])a_double_marray_fixed_read.Array_,
                                          new double[] { 0.29, 0.41, 0.4, 0.66, 0.6, 0.2 }));
    c.a_double_marray_fixed = new MultiDimArray(new uint[] { 3, 2 }, new double[] { 0.3, 0.4, 0.5, 0.6, 0.6, 0.2 });
    // property double[*] a_double_marray
    var a_double_marray_read = c.a_double_marray;
    Debug.Assert(Enumerable.SequenceEqual(a_double_marray_read.Dims, new uint[] { 2, 2 }));
    Debug.Assert(
        Enumerable.SequenceEqual((double[])a_double_marray_read.Array_, new double[] { 0.72, 0.05, 0.4, 0.07 }));
    c.a_double_marray = new MultiDimArray(new uint[] { 2, 1 }, new double[] { 0.3, 0.01 });
    // property uint8[] c_byte_array
    Debug.Assert(Enumerable.SequenceEqual(c.c_byte_array, new byte[] { 0x1A, 0x2B }));
    c.c_byte_array = new byte[] { 0x3C, 0x4D, 0x5E, 0x6F, 0x70 };
}

// numeric_value_types.cpp - Example of using numeric value types

#include <stdio.h>
#include <iostream>
#include <boost/range/algorithm.hpp>
#include <RobotRaconteur.h>
#include "robotraconteur_generated.h"

// Only use the RR alias in cpp files. Do not use it in header files.
namespace RR = RobotRaconteur;
namespace vt = experimental::value_types;

template <typename T>
void assert_array(const RR::RRArrayPtr<T>& a, const std::vector<T>& b)
{
    assert(a->size() == b.size());
    // RRArray supports standard C++ iterator interface.
    // The intrusive_ptr smart pointer
    // is dereferenced to access the underlying RRArray.
    assert(boost::range::equal(*a, b));
}

int main(int argc, char* argv[])
{
    RR::ClientNodeSetup node_setup(ROBOTRACONTEUR_SERVICE_TYPES, argc, argv);

    vt::ValueTypesExamplePtr c = RR::rr_cast<vt::ValueTypesExample>(
        RR::RobotRaconteurNode::s()->ConnectService("rr+tcp://localhost:53223?service=values_example"));

    // Scalar numbers
    // property double a_double
    double a_double_read = c->get_a_double();
    std::cout << a_double_read << std::endl;
    // assert used for the rest of the example property read operations
    // to demonstrate the expected values.
    assert(c->get_a_double() == 5.78);
    c->set_a_double(49.3);
    // property int32 b_int
    assert(c->get_b_int() == 4557);
    c->set_b_int(359);
    // property uint8 c_byte
    assert(c->get_c_byte() == 0x1A);
    c->set_c_byte(31);
    // property cdouble d_cdouble
    assert(c->get_d_cdouble() == RR::cdouble(23.7, 5.3));
    c->set_d_cdouble(RR::cdouble(1.2, 3.4));
    // property bool e_bool
    // RR::rr_bool is used for Robot Raconteur bool values
    assert(c->get_e_bool().value != 0);
    c->set_e_bool(RR::rr_bool(0));
    // property int32 meaning_of_life [readonly]
    assert(c->get_meaning_of_life() == 42);

    // Numeric Arrays
    // property double[] a_double_array
    assert_array(c->get_a_double_array(), {0.016, 0.226});

    // Examples of different ways to initialize RRArray. Also see Eigen converters in robotraconteur-companion

    // Use AttachRRArrayCopy()
    double a_double_array_1a[] = {0.582, 0.288, 0.09, 0.213, 0.98};
    RR::RRArrayPtr<double> a_double_array_1 = RR::AttachRRArrayCopy(a_double_array_1a, 5);
    c->set_a_double_array(a_double_array_1);

    // Use AllocateRRArray to allocate an uninitialized array
    RR::RRArrayPtr<double> a_double_array_2 = RR::AllocateRRArray<double>(5);
    a_double_array_2->at(0) = 0.582;
    a_double_array_2->at(1) = 0.288;
    a_double_array_2->at(2) = 0.09;
    a_double_array_2->at(3) = 0.213;
    a_double_array_2->at(4) = 0.98;
    c->set_a_double_array(a_double_array_2);

    RR::RRArrayPtr<double> a_double_array_2b = c->get_a_double_array();
    assert(a_double_array_2b->size() == 2);
    assert(a_double_array_2b->at(0) == 0.016);
    assert((*a_double_array_2b)[1] == 0.226);

    // Use VectorToRRArray to convert a std::vector to RRArray
    std::vector<double> a_double_array_3a = {0.582, 0.288, 0.09, 0.213, 0.98};
    RR::RRArrayPtr<double> a_double_array_3 = RR::VectorToRRArray<double, double>(a_double_array_3a);
    c->set_a_double_array(a_double_array_3);

    // property double[3] a_double_array_fixed
    assert_array(c->get_a_double_array_fixed(), {0.13, 0.27, 0.15});
    c->set_a_double_array_fixed(RR::VectorToRRArray<double, double>({0.21, 0.12, 0.39}));
    // % property double[6-] a_double_array_maxlen
    assert_array(c->get_a_double_array_maxlen(), {0.7, 0.16, 0.16, 0.05, 0.61, 0.9});
    c->set_a_double_array_maxlen(RR::VectorToRRArray<double, double>({0.035, 0.4}));
    // property double[3,2] a_double_marray_fixed
    RR::RRMultiDimArrayPtr<double> a_double_marray_fixed_read = c->get_a_double_marray_fixed();
    assert_array(a_double_marray_fixed_read->Dims, {3, 2});
    assert_array(a_double_marray_fixed_read->Array, {0.29, 0.41, 0.4, 0.66, 0.6, 0.2});
    RR::RRMultiDimArrayPtr<double> a_double_marray_fixed_1 =
        RR::AllocateRRMultiDimArray<double>(RR::VectorToRRArray<uint32_t, uint32_t>({3, 2}),
                                            RR::VectorToRRArray<double, double>({0.3, 0.4, 0.5, 0.6, 0.6, 0.2}));
    c->set_a_double_marray_fixed(a_double_marray_fixed_1);
    // property double[*] a_double_marray
    RR::RRMultiDimArrayPtr<double> a_double_marray_read = c->get_a_double_marray();
    assert_array(a_double_marray_read->Dims, {2, 2});
    assert_array(a_double_marray_read->Array, {0.72, 0.05, 0.4, 0.07});
    RR::RRMultiDimArrayPtr<double> a_double_marray_1 = RR::AllocateRRMultiDimArray<double>(
        RR::VectorToRRArray<uint32_t, uint32_t>({2, 1}), RR::VectorToRRArray<double, double>({0.3, 0.01}));
    // property uint8[] c_byte_array
    assert_array(c->get_c_byte_array(), {0x1A, 0x2B});
    c->set_c_byte_array(RR::VectorToRRArray<uint8_t, uint8_t>({0x3C, 0x4D, 0x5E, 0x6F, 0x70}));

    std::cout << "numeric_value_types.cpp example complete" << std::endl;
    return 0;
}

String Type

Robot Raconteur uses the built-in string types in the client programming language. Note that strings cannot be stored in arrays since internally strings are already stored as arrays of characters.

The following members from the experimental.value_types.ValueTypesExample object are used in the examples for numeric types:

    property string f_string

The examples below show how to use strings in Python, MATLAB, LabView, C#, and C++.

# string_value_type.py - Example of using string value types

from RobotRaconteur.Client import *
import numpy as np

c = RRN.ConnectService('rr+tcp://localhost:53223?service=values_example')

# Strings
# property string f_string
f_string_read = c.f_string
print(f_string_read)
# assert is used for the rest of the example property read operations
# to demonstrate the expected values.
assert (c.f_string == "An example string read from the service")
c.f_string = "An example string written to the service"

% string_value_type.m - Example of using string value types

c = RobotRaconteur.ConnectService('rr+tcp://localhost:53223?service=values_example');

% Strings
% property string f_string
f_string_read = c.f_string;
disp(f_string_read);
% assert is used for the rest of the example property read operations
% to demonstrate the expected values.
assert (strcmp(c.f_string, 'An example string read from the service'));
c.f_string = 'An example string written to the service';

RobotRaconteur.DisconnectService(c);

// string_value_type.cs - Example of using string value types

using RobotRaconteur;
using System;
using System.Diagnostics;
using System.Linq;

using (var node_setup = new ClientNodeSetup(args))
{

    var c = (experimental.value_types.ValueTypesExample)RobotRaconteurNode.s.ConnectService(
        "rr+tcp://localhost:53223?service=values_example");

    // Strings
    // property string f_string
    var f_string_read = c.f_string;
    Console.WriteLine(f_string_read);
    // assert is used for the rest of the example property read operations
    // to demonstrate the expected values.
    Debug.Assert(c.f_string == "An example string read from the service");
    c.f_string = "An example string written to the service";
}

// string_value_type.cpp - Example of using string value types

#include <stdio.h>
#include <iostream>
#include <boost/range/algorithm.hpp>
#include <RobotRaconteur.h>
#include "robotraconteur_generated.h"

// Only use the RR alias in cpp files. Do not use it in header files.
namespace RR = RobotRaconteur;
namespace vt = experimental::value_types;

int main(int argc, char* argv[])
{
    RR::ClientNodeSetup node_setup(ROBOTRACONTEUR_SERVICE_TYPES, argc, argv);

    vt::ValueTypesExamplePtr c = RR::rr_cast<vt::ValueTypesExample>(
        RR::RobotRaconteurNode::s()->ConnectService("rr+tcp://localhost:53223?service=values_example"));

    // Strings
    // property string f_string
    std::string f_string_read = c->get_f_string();
    std::cout << f_string_read << std::endl;
    // assert is used for the rest of the example property read operations
    // to demonstrate the expected values.
    assert(c->get_f_string() == "An example string read from the service");
    c->set_f_string("An example string written to the service");

    std::cout << "string_value_type.cpp example complete" << std::endl;
    return 0;
}

Structure Types

Structures are a collection of fields that can contain any value type, including itself. Structures are defined using the Robot Raconteur “Service Definitions” format. Structures are nullable. The following examples demonstrate using the experimental.value_types.MyStructure structure type:

# Structure examples.
struct MyStructure
    # struct fields can be any value type
    field double a
    field uint32[2] b
    field string c
    field string{list} d
end

The following members from the experimental.value_types.ValueTypesExample object are used in the examples for structure types:

    property MyStructure k_struct

The examples below show how to use structures in Python, MATLAB, LabView, C#, and C++.

# struct_value_type.py - Simple example of using struct value types

from RobotRaconteur.Client import *
import numpy as np

c = RRN.ConnectService('rr+tcp://localhost:53223?service=values_example')

# Example using MyStructure type. Also see example
# using MyStructure for a more complex example.

# Retrieve the structure type. obj is only used
# for clients. It is omitted for services.
my_structure_type = RRN.GetStructureType("experimental.value_types.MyStructure", obj=c)

# Create and populate a MyStructure
s = my_structure_type()
# field double a
s.a = 5
# field uint32[2] b
s.b = np.array([10, 20], dtype=np.uint32)
# field string c
s.c = "String from structure client"
# field string{list} d
s.d = [
    "string a",
    "string b"
]

# Set the property using the structure
# property MyStructure k_struct
c.k_struct = s

# Retrieve the structure from the service
u = c.k_struct

# Structures can be None
assert u is not None

# field double a
assert (u.a == 52)
# field uint32[2] b
np.testing.assert_array_equal(u.b, np.array([110, 120], dtype=np.uint32))
# field string c
assert (u.c == "String from structure service")
# field string{list} d
assert (len(u.d) == 3)
assert (u.d[0] == "string c")
assert (u.d[1] == "string d")
assert (u.d[2] == "string e")

% struct_value_type.m - Simple example of using struct value types

c = RobotRaconteur.ConnectService('rr+tcp://localhost:53223?service=values_example');

% Create and populate a MyStructure
s = RobotRaconteur.CreateStructure(c, 'experimental.value_types.MyStructure');
% field double a
s.a = 5;
% field uint32[2] b
s.b = uint32([10, 20]');
% field string c
s.c = 'String from structure client';
% field string{list} d
s.d = {'string a','string b'}';


% Set the property using the structure
% property MyStructure k_struct
c.k_struct = s;

% Retrieve the structure from the service
u = c.k_struct;

% Structures can be None
assert(~ismissing(u));

% field double a
assert (u.a == 52);
% field uint32[2] b
assert(isequal(u.b, [110, 120]'));
% field string c
assert (strcmp(u.c, 'String from structure service'));
% field string{list} d
assert (length(u.d) == 3);
assert (strcmp(u.d{1}, 'string c'));
assert (strcmp(u.d{2}, 'string d'));
assert (strcmp(u.d{3}, 'string e'));

RobotRaconteur.DisconnectService(c);

// struct_value_type.cs - Simple example of using struct value types

using RobotRaconteur;
using System;
using System.Diagnostics;
using System.Linq;
using experimental.value_types;

using (var node_setup = new ClientNodeSetup(args))
{
    var c = (experimental.value_types.ValueTypesExample)RobotRaconteurNode.s.ConnectService(
        "rr+tcp://localhost:53223?service=values_example");

    // Create and populate a MyStructure
    var s = new MyStructure();
    // field double a
    s.a = 5;
    // field uint32[2] b
    s.b = new uint[] { 10, 20 };
    // field string c
    s.c = "String from structure client";
    // field string{list} d
    s.d = new List<string>( { "string a", "string b" });

    // Set the property using the structure
    // property MyStructure k_struct
    c.k_struct = s;

    // Retrieve the structure from the service
    var u = c.k_struct;

    // Structures can be None
    Debug.Assert(u != null);

    // field double a
    Debug.Assert(u.a == 52);
    // field uint32[2] b
    Debug.Assert(Enumerable.SequenceEqual(u.b, new uint[] { 110, 120 }));
    // field string c
    Debug.Assert(u.c == "String from structure service");
    // field string{list} d
    Debug.Assert(Enumerable.SequenceEqual(u.d, new List<string>( { "string c", "string d", "string e" })));
}

// struct_value_type.cpp - Simple example of using struct value types

#include <stdio.h>
#include <iostream>
#include <boost/range/algorithm.hpp>
#include <RobotRaconteur.h>
#include "robotraconteur_generated.h"

// Only use the RR alias in cpp files. Do not use it in header files.
namespace RR = RobotRaconteur;
namespace vt = experimental::value_types;

template <typename T>
void assert_array(const RR::RRArrayPtr<T>& a, const std::vector<T>& b)
{
    assert(a->size() == b.size());
    // RRArray supports standard C++ iterator interface.
    // The intrusive_ptr smart pointer
    // is dereferenced to access the underlying RRArray.
    assert(boost::range::equal(*a, b));
}

int main(int argc, char* argv[])
{
    RR::ClientNodeSetup node_setup(ROBOTRACONTEUR_SERVICE_TYPES, argc, argv);

    vt::ValueTypesExamplePtr c = RR::rr_cast<vt::ValueTypesExample>(
        RR::RobotRaconteurNode::s()->ConnectService("rr+tcp://localhost:53223?service=values_example"));

    // Create and populate a MyStructure
    vt::MyStructurePtr s(new vt::MyStructure());
    // field double a
    s->a = 5;
    // field uint32[2] b
    s->b = RR::VectorToRRArray<uint32_t, uint32_t>({10, 20});
    // field string c
    s->c = "String from structure client";
    // field string{list} d
    // Strings are stored in RRArray<char> when stored in containers
    RR::RRListPtr<RR::RRArray<char> > d1 = RR::AllocateEmptyRRList<RR::RRArray<char> >();
    d1->push_back(RR::stringToRRArray("string a"));
    d1->push_back(RR::stringToRRArray("string b"));
    s->d = d1;

    // Set the property using the structure
    // property MyStructure k_struct
    c->set_k_struct(s);

    // Retrieve the structure from the service
    vt::MyStructurePtr u = c->get_k_struct();

    // Structures can be None
    RR::rr_null_check(u);

    // field double a
    assert(u->a == 52);
    // field uint32[2] b
    assert_array(u->b, {110, 120});
    // field string c
    assert(u->c == "String from structure service");
    // field string{list} d
    // Containers can be null
    RR::rr_null_check(u->d);
    assert(u->d->size() == 3);
    auto d2_iterator = u->d->begin();
    assert(RR::RRArrayToString(*d2_iterator++) == "string c");
    assert(RR::RRArrayToString(*d2_iterator++) == "string d");
    assert(RR::RRArrayToString(*d2_iterator++) == "string e");

    std::cout << "struct_value_types.cpp example complete" << std::endl;
    return 0;
}

Pod Types

Pods are a collections of fields that have a fixed memory layout. Pods have a restricted set of allowed field types including numbers, arrays, namedarrays, and other pods. See the Robot Raconteur Framework Service Definition Documentation for more information about the allowed contents of pods. Unlike structures, pods store all their data within the pod itself in contiguous memory, and do not contain pointers to other data. They are guaranteed to have a maximum binary size. The following examples demonstrate using the experimental.value_types.MyPod pod type:

# Pod example. Only numeric types, other pods, and namedarrays can
# be used in a pod. All arrays must have a fixed or maximum length.
# Multidimarrays must be fixed. Pods have a fixed maximum binary
# size to fit in contiguous memory. Pods do not
# have to have the same underlying numeric type for all the
# fields.
pod MyPod
    field double a
    field int32 b
    field uint8[4] c
    field uint8[4-] d
    field uint16[2,3] e
    field MyVector3 f
end

The following members from the experimental.value_types.ValueTypesExample object are used in the examples for pod types:

    # Examples using pods
    property MyPod j_pod
    property MyPod[] j_pod_array

The examples below show how to use pods in Python, MATLAB, LabView, C#, and C++.

# pod_value_types.py - Example of using pod value types

from RobotRaconteur.Client import *
import numpy as np

c = RRN.ConnectService('rr+tcp://localhost:53223?service=values_example')

# Example using Pod numpy dtypes. Pods are represented as NumPy dtypes with fields
# obj is only used for clients. It is omitted for services.
my_pod_dtype = RRN.GetPodDType("experimental.value_types.MyPod", obj=c)

# property MyPod j_pod
a = np.zeros((1,), dtype=my_pod_dtype)
a[0]["a"] = 0.928
a[0]["b"] = 8374
a[0]["c"] = [8, 9, 10, 11]
# Max length fields are stored with a length field and
# data field.
a[0]["d"]["len"] = 1
a[0]["d"]["array"][0] = 17
a[0]["e"] = [[1, 2, 3], [4, 5, 6]]
a[0]["f"]["x"] = 10.1
a[0]["f"]["y"] = 10.2
a[0]["f"]["z"] = 10.3
c.j_pod = a

b = c.j_pod
assert (b[0]["a"] == 0.791)
assert (b[0]["b"] == 1077)
np.testing.assert_array_equal(b[0]["c"], [61, 52, 33, 24])
assert (b[0]["d"]["len"] == 2)
np.testing.assert_array_equal(b[0]["d"]["array"][0:2], [1, 2])
np.testing.assert_array_equal(b[0]["e"], [[7, 8, 9], [10, 11, 12]])
assert (b[0]["f"]["x"] == 20.1)
assert (b[0]["f"]["y"] == 20.2)
assert (b[0]["f"]["z"] == 20.3)

# Now an array of Pods
# property MyPod[] j_pod_array
d = np.zeros((2,), dtype=my_pod_dtype)
d[0]["a"] = 0.928
d[0]["b"] = 8374
d[0]["c"] = [8, 9, 10, 11]
d[0]["d"]["len"] = 1
d[0]["d"]["array"][0] = 17
d[0]["e"] = [[1, 2, 3], [4, 5, 6]]
d[0]["f"]["x"] = 10.1
d[0]["f"]["y"] = 10.2
d[0]["f"]["z"] = 10.3
d[1]["a"] = 0.67
d[1]["b"] = 123
d[1]["c"] = [1, 2, 3, 4]
d[1]["d"]["len"] = 2
d[1]["d"]["array"][0:2] = [5, 6]
d[1]["e"] = [[13, 14, 15], [16, 17, 18]]
d[1]["f"]["x"] = 30.1
d[1]["f"]["y"] = 30.2
d[1]["f"]["z"] = 30.3
c.j_pod_array = d

e = c.j_pod_array
assert (e[0]["a"] == 0.791)
assert (e[0]["b"] == 1077)
np.testing.assert_array_equal(e[0]["c"], [61, 52, 33, 24])
assert (e[0]["d"]["len"] == 2)
np.testing.assert_array_equal(e[0]["d"]["array"][0:2], [1, 2])
np.testing.assert_array_equal(e[0]["e"], [[7, 8, 9], [10, 11, 12]])
assert (e[0]["f"]["x"] == 20.1)
assert (e[0]["f"]["y"] == 20.2)
assert (e[0]["f"]["z"] == 20.3)
assert (e[1]["a"] == 0.03)
assert (e[1]["b"] == 693)
np.testing.assert_array_equal(e[1]["c"], [5, 6, 7, 8])
assert (e[1]["d"]["len"] == 1)
np.testing.assert_array_equal(e[1]["d"]["array"][0:1], [3])
np.testing.assert_array_equal(e[1]["e"], [[19, 20, 21], [22, 23, 24]])
assert (e[1]["f"]["x"] == 40.1)
assert (e[1]["f"]["y"] == 40.2)
assert (e[1]["f"]["z"] == 40.3)

% pod_value_types.m - Example of using pod value types

c = RobotRaconteur.ConnectService('rr+tcp://localhost:53223?service=values_example');

% Example using Pods. Pods are represented as Matlab struct

% property MyPod j_pod
a = struct;
a.a = 0.928;
a.b = int32(8374);
a.c = uint8([8, 9, 10, 11]');
a.d = uint8(17);
a.e = uint16([1, 2, 3; 4, 5, 6]);
a.f = [10.1, 10.2, 10.3]';
c.j_pod = a;

b = c.j_pod;
assert (b.a == 0.791)
assert (b.b == 1077)
assert(isequal(b.c, [61, 52, 33, 24]'));
assert(isequal(b.d, [1, 2]'));
assert(isequal(b.e, [7, 8, 9; 10, 11, 12]));
assert (isequal(b.f, [20.1, 20.2, 20.3]'));

% Now an array of Pods
% property MyPod[] j_pod_array
d = struct;
d.a = 0.928;
d.b = int32(8374);
d.c = uint8([8, 9, 10, 11]');
d.d = uint8(17);
d.e = uint16([1, 2, 3; 4, 5, 6]);
d.f = [10.1, 10.2, 10.3]';
d2 = struct;
d2.a = 0.67;
d2.b = int32(123);
d2.c = uint8([1, 2, 3, 4]');
d2.d = uint8([5, 6]');
d2.e = uint16([13, 14, 15; 16, 17, 18]);
d2.f = [30.1, 30.2, 30.3]';
d(2,1) = d2;
c.j_pod_array = d;

e = c.j_pod_array;
assert(e(1).a == 0.791);
assert(e(1).b == 1077);
assert(isequal(e(1).c, [61, 52, 33, 24]'));
assert(isequal(e(1).d, [1, 2]'));
assert(isequal(e(1).e, [7, 8, 9; 10, 11, 12]));
assert(isequal(e(1).f, [20.1, 20.2, 20.3]'));
assert(e(2).a == 0.03);
assert(e(2).b == 693);
assert(isequal(e(2).c, [5, 6, 7, 8]'));
assert(isequal(e(2).d, 3));
assert(isequal(e(2).e, [19, 20, 21; 22, 23, 24]));
assert(isequal(e(2).f, [40.1, 40.2, 40.3]'));

RobotRaconteur.DisconnectService(c);

// pod_value_types.cs - Example of using pod value types

using RobotRaconteur;
using System;
using System.Diagnostics;
using System.Linq;
using experimental.value_types;

using (var node_setup = new ClientNodeSetup(args))
{
    var c = (experimental.value_types.ValueTypesExample)RobotRaconteurNode.s.ConnectService(
        "rr+tcp://localhost:53223?service=values_example");

    // Example using Pods

    // property MyPod j_pod
    var a = new MyPod() { a = 0.928,
                          b = 8374,
                          c = new byte[] { 8, 9, 10, 11 },
                          d = new byte[] { 17 },
                          e = new ushort[] { 1, 4, 2, 5, 3, 6 },
                          f = new MyVector3() { x = 10.1, y = 10.2, z = 10.3 } };
    c.j_pod = a;

    var b = c.j_pod;
    Debug.Assert(b.a == 0.791);
    Debug.Assert(b.b == 1077);
    Debug.Assert(Enumerable.SequenceEqual(b.c, new byte[] { 61, 52, 33, 24 }));
    Debug.Assert(Enumerable.SequenceEqual(b.d, new byte[] { 1, 2 }));
    Debug.Assert(Enumerable.SequenceEqual(b.e, new ushort[] { 7, 10, 8, 11, 9, 12 }));
    Debug.Assert(b.f.x == 20.1);
    Debug.Assert(b.f.y == 20.2);
    Debug.Assert(b.f.z == 20.3);

    // Now an array of Pods
    // property MyPod[] j_pod_array
    var d = new MyPod[] { new MyPod() { a = 0.928, b = 8374, c = new byte[] { 8, 9, 10, 11 }, d = new byte[] { 17 },
                                        e = new ushort[] { 1, 4, 2, 5, 3, 6 },
                                        f = new MyVector3() { x = 10.1, y = 10.2, z = 10.3 } },
                          new MyPod() { a = 0.67, b = 123, c = new byte[] { 1, 2, 3, 4 }, d = new byte[] { 5, 6 },
                                        e = new ushort[] { 13, 16, 14, 17, 15, 18 },
                                        f = new MyVector3() { x = 30.1, y = 30.2, z = 30.3 } } };
    c.j_pod_array = d;

    var e = c.j_pod_array;
    Debug.Assert(e[0].a == 0.791);
    Debug.Assert(e[0].b == 1077);
    Debug.Assert(Enumerable.SequenceEqual(e[0].c, new byte[] { 61, 52, 33, 24 }));
    Debug.Assert(Enumerable.SequenceEqual(e[0].d, new byte[] { 1, 2 }));
    Debug.Assert(Enumerable.SequenceEqual(e[0].e, new ushort[] { 7, 10, 8, 11, 9, 12 }));
    Debug.Assert(e[0].f.x == 20.1);
    Debug.Assert(e[0].f.y == 20.2);
    Debug.Assert(e[0].f.z == 20.3);
    Debug.Assert(e[1].a == 0.03);
    Debug.Assert(e[1].b == 693);
    Debug.Assert(Enumerable.SequenceEqual(e[1].c, new byte[] { 5, 6, 7, 8 }));
    Debug.Assert(Enumerable.SequenceEqual(e[1].d, new byte[] { 3 }));
    Debug.Assert(Enumerable.SequenceEqual(e[1].e, new ushort[] { 19, 22, 20, 23, 21, 24 }));
    Debug.Assert(e[1].f.x == 40.1);
    Debug.Assert(e[1].f.y == 40.2);
    Debug.Assert(e[1].f.z == 40.3);
}

// pod_value_types.cpp - Example of using pod value types

#include <stdio.h>
#include <iostream>
#include <boost/range/algorithm.hpp>
#include <RobotRaconteur.h>
#include "robotraconteur_generated.h"

// Only use the RR alias in cpp files. Do not use it in header files.
namespace RR = RobotRaconteur;
namespace vt = experimental::value_types;

template <typename T>
void assert_array(const RR::RRArrayPtr<T>& a, const std::vector<T>& b)
{
    assert(a->size() == b.size());
    // RRArray supports standard C++ iterator interface.
    // The intrusive_ptr smart pointer
    // is dereferenced to access the underlying RRArray.
    assert(boost::range::equal(*a, b));
}

int main(int argc, char* argv[])
{
    RR::ClientNodeSetup node_setup(ROBOTRACONTEUR_SERVICE_TYPES, argc, argv);

    vt::ValueTypesExamplePtr c = RR::rr_cast<vt::ValueTypesExample>(
        RR::RobotRaconteurNode::s()->ConnectService("rr+tcp://localhost:53223?service=values_example"));

    // Example using Pods

    // property MyPod j_pod
    vt::MyPod a;
    a.a = 0.928;
    a.b = 8374;
    a.c[0] = 8;
    a.c[1] = 9;
    a.c[2] = 10;
    a.c[3] = 11;
    a.d.resize(1);
    a.d[0] = 17;
    double a_e[6] = {1, 4, 2, 5, 3, 6};
    memcpy(&a.e[0], a_e, sizeof(a_e));
    a.f.s.x = 10.1;
    a.f.s.y = 10.2;
    a.f.s.z = 10.3;
    c->set_j_pod(a);

    vt::MyPod b = c->get_j_pod();
    assert(b.a == 0.791);
    assert(b.b == 1077);
    double b_c[4] = {61, 52, 33, 24};
    assert(memcmp(&b.c[0], b_c, sizeof(b_c)) == 0);
    assert(b.d.size() == 2);
    double b_d[2] = {1, 2};
    assert(memcmp(&b.d[0], b_d, sizeof(b_d)) == 0);
    double b_e[6] = {7, 10, 8, 11, 9, 12};
    assert(memcmp(&b.e[0], b_e, sizeof(b_e)) == 0);
    vt::MyVector3 b_f = b.f;
    assert(b_f.s.x == 20.1);
    assert(b_f.s.y == 20.2);
    assert(b_f.s.z == 20.3);

    // Now an array of Pods
    // property MyPod[] j_pod_array
    RR::RRPodArrayPtr<vt::MyPod> d = RR::AllocateEmptyRRPodArray<vt::MyPod>(2);
    d->at(0).a = 0.928;
    d->at(0).b = 8374;
    double d0_c[] = {8, 9, 10, 11};
    memcpy(&d->at(0).c[0], d0_c, sizeof(d0_c));
    d->at(0).d.resize(1);
    d->at(0).d[0] = 17;
    double d0_e[6] = {1, 4, 2, 5, 3, 6};
    memcpy(&d->at(0).e[0], d0_e, sizeof(d0_e));
    d->at(0).f.s.x = 10.1;
    d->at(0).f.s.y = 10.2;
    d->at(0).f.s.z = 10.3;

    d->at(1).a = 0.67;
    d->at(1).b = 123;
    double d1_c[] = {1, 2, 3, 4};
    memcpy(&d->at(1).c[0], d1_c, sizeof(d1_c));
    d->at(1).d.resize(2);
    double d1_d[] = {5, 6};
    memcpy(&d->at(1).d[0], d1_d, sizeof(d1_d));
    double d1_e[6] = {13, 16, 14, 17, 15, 18};
    memcpy(&d->at(1).e[0], d1_e, sizeof(d1_e));
    d->at(1).f.s.x = 30.1;
    d->at(1).f.s.y = 30.2;
    d->at(1).f.s.z = 30.3;

    c->set_j_pod_array(d);

    RR::RRPodArrayPtr<vt::MyPod> f = c->get_j_pod_array();
    assert(f->size() == 2);
    assert(f->at(0).a == 0.791);
    assert(f->at(0).b == 1077);
    double f0_c[4] = {61, 52, 33, 24};
    assert(memcmp(&f->at(0).c[0], f0_c, sizeof(f0_c)) == 0);
    assert(f->at(0).d.size() == 2);
    double f0_d[2] = {1, 2};
    assert(memcmp(&f->at(0).d[0], f0_d, sizeof(f0_d)) == 0);
    double f0_e[6] = {7, 10, 8, 11, 9, 12};
    assert(memcmp(&f->at(0).e[0], f0_e, sizeof(f0_e)) == 0);
    vt::MyVector3 f0_f = f->at(0).f;
    assert(f0_f.s.x == 20.1);
    assert(f0_f.s.y == 20.2);
    assert(f0_f.s.z == 20.3);

    assert(f->at(1).a == 0.03);
    assert(f->at(1).b == 693);
    double f1_c[4] = {5, 6, 7, 8};
    assert(memcmp(&f->at(1).c[0], f1_c, sizeof(f1_c)) == 0);
    assert(f->at(1).d.size() == 1);
    double f1_d[1] = {3};
    assert(memcmp(&f->at(1).d[0], f1_d, sizeof(f1_d)) == 0);
    double f1_e[6] = {19, 22, 20, 23, 21, 24};
    assert(memcmp(&f->at(1).e[0], f1_e, sizeof(f1_e)) == 0);
    vt::MyVector3 f1_f = f->at(1).f;
    assert(f1_f.s.x == 40.1);
    assert(f1_f.s.y == 40.2);
    assert(f1_f.s.z == 40.3);

    std::cout << "pod_value_types.cpp example complete" << std::endl;
    return 0;
}

NamedArray Types

Namedarrays represent a union type between a structure and a numeric array. A vector is an example of a type that can be represented either as a structure with three fields, or as a numeric array with three elements. Namedarrays are very efficient compared to the other data types since they can be transmitted or manipulated as a plain array. All fields in the namedarray must have the same numeric type. Other namedarrays and arrays may also be used as fields, but they must have the same underlying numeric type and a fixed size. The following examples demonstrate using the experimental.value_types.MyVector3, experimental.value_types.MyQuaternion, and experimental.value_types.MyPose namedarray types:

# Example vector namedarray. Note that all fields must
# have the same underlying numeric type
namedarray MyVector3
    field double x
    field double y
    field double z
end

namedarray MyQuaternion
    field double w
    field double x
    field double y
    field double z
end

# Example pose namedarray using composition of other namedarrays.
# All underlying fields must have the same numeric type.
namedarray MyPose
    field MyQuaternion orientation
    field MyVector3 position
end

The following members from the experimental.value_types.ValueTypesExample object are used in the examples for namedarray types:

    # Examples using namedarray
    property MyVector3 g_vector
    property MyVector3[] g_vector_array
    property MyQuaternion h_quaternion
    property MyPose i_pose

The examples below show how to use namedarrays in Python, MATLAB, LabView, C#, and C++.

# namedarray_value_types.py - Example of using namedarray value types

from RobotRaconteur.Client import *
import numpy as np

c = RRN.ConnectService('rr+tcp://localhost:53223?service=values_example')

# Retrieve NamedArray numpy dtypes. NamedArrays are represented as NumPy dtypes with fields
# obj is only used for clients. It is omitted for services.
my_vector3_dtype = RRN.GetNamedArrayDType("experimental.value_types.MyVector3", obj=c)
my_quaternion_dtype = RRN.GetNamedArrayDType("experimental.value_types.MyQuaternion", obj=c)
my_pose_dtype = RRN.GetNamedArrayDType("experimental.value_types.MyPose", obj=c)

# NumPy structures are used to represent NamedArrays.
# These structures can also be converted to and from plain arrays of the
# underlying numeric type using RRN.NamedArrayToArray() and RRN.ArrayToNamedArray().
# Scalar NamedArrays are represented as arrays with a single element.

# property MyVector3 g_vector
a = np.zeros((1,), dtype=my_vector3_dtype)
a[0]["x"] = 1.0
a[0]["y"] = 2.0
a[0]["z"] = 3.0
c.g_vector = a

b = c.g_vector
assert (b[0]["x"] == 4.0)
assert (b[0]["y"] == 5.0)
assert (b[0]["z"] == 6.0)

# Use plain arrays and convert to and from NamedArrays
d = np.array([1.0, 2.0, 3.0], dtype=np.float64)
c.g_vector = RRN.ArrayToNamedArray(d, named_array_dt=my_vector3_dtype)
e = RRN.NamedArrayToArray(c.g_vector)
np.testing.assert_array_equal(e, [[4.0, 5.0, 6.0]])

# Now an array of NamedArrays
# property MyVector3[] g_vector_array
f = np.zeros((2,), dtype=my_vector3_dtype)
f[0]["x"] = 1.0
f[0]["y"] = 2.0
f[0]["z"] = 3.0
f[1]["x"] = 4.0
f[1]["y"] = 5.0
f[1]["z"] = 6.0
c.g_vector_array = f

g = c.g_vector_array
assert (g[0]["x"] == 7.0)
assert (g[0]["y"] == 8.0)
assert (g[0]["z"] == 9.0)
assert (g[1]["x"] == 10.0)
assert (g[1]["y"] == 11.0)
assert (g[1]["z"] == 12.0)

# Use plain arrays and convert to and from NamedArrays
h = np.array([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]], dtype=np.float64)
c.g_vector_array = RRN.ArrayToNamedArray(h, named_array_dt=my_vector3_dtype)
i = RRN.NamedArrayToArray(c.g_vector_array)
np.testing.assert_array_equal(i, [[7.0, 8.0, 9.0], [10.0, 11.0, 12.0]])

# property MyQuaternion h_quaternion
j = np.zeros((1,), dtype=my_quaternion_dtype)
j[0]["w"] = 1.0
j[0]["x"] = 0.0
j[0]["y"] = 0.0
j[0]["z"] = 0.0
c.h_quaternion = j

k = c.h_quaternion
assert (k[0]["w"] == 0.707)
assert (k[0]["x"] == 0.0)
assert (k[0]["y"] == 0.707)
assert (k[0]["z"] == 0.0)

# MyPose is a composite NamedArray with fields of other NamedArrays
# property MyPose l_pose
l = np.zeros((1,), dtype=my_pose_dtype)
l[0]["orientation"]["w"] = 1.0
l[0]["orientation"]["x"] = 0.0
l[0]["orientation"]["y"] = 0.0
l[0]["orientation"]["z"] = 0.0
l[0]["position"]["x"] = 1.0
l[0]["position"]["y"] = 2.0
l[0]["position"]["z"] = 3.0
c.i_pose = l

m = c.i_pose
assert (m[0]["orientation"]["w"] == 0.707)
assert (m[0]["orientation"]["x"] == 0.0)
assert (m[0]["orientation"]["y"] == 0.707)
assert (m[0]["orientation"]["z"] == 0.0)
assert (m[0]["position"]["x"] == 4.0)
assert (m[0]["position"]["y"] == 5.0)
assert (m[0]["position"]["z"] == 6.0)

# Use plain arrays and convert to and from NamedArrays
n = np.array([1.0, 0.0, 0.0, 0.0, 1.0, 2.0, 3.0,], dtype=np.float64)
c.i_pose = RRN.ArrayToNamedArray(n, named_array_dt=my_pose_dtype)
o = RRN.NamedArrayToArray(c.i_pose)
np.testing.assert_array_equal(o, [[0.707, 0.0, 0.707, 0.0, 4.0, 5.0, 6.0]])

% namedarray_value_types.m - Example of using namedarray value types

c = RobotRaconteur.ConnectService('rr+tcp://localhost:53223?service=values_example');

% Robot Raconteur uses the array format for namedarray in Matlab

% property MyVector3 g_vector

c.g_vector = [1.0, 2.0, 3.0]';
b=c.g_vector;
assert (isequal(b,[4.0, 5.0, 6.0]'));

% Now an array of NamedArrays
% property MyVector3[] g_vector_array
f = [1.0,2.0,3.0;4.0,5.0,6.0]';
c.g_vector_array = f;

g = c.g_vector_array;
assert(isequal(g,[7.0,8.0,9.0;10.0,11.0,12.0]'));

% property MyQuaternion h_quaternion
j = [1.0, 0.0, 0.0, 0.0]';
c.h_quaternion = j;

k = c.h_quaternion;
assert(isequal(k, [0.707, 0.0, 0.707, 0.0]'));

% MyPose is a composite NamedArray with fields of other NamedArrays
% property MyPose l_pose
l = [1.0, 0.0, 0.0, 0.0, 1.0, 2.0, 3.0]';
c.i_pose = l;

m = c.i_pose;
assert(isequal(m, [0.707, 0.0, 0.707, 0.0, 4.0, 5.0, 6.0]'));

RobotRaconteur.DisconnectService(c);

// namedarray_value_types.cs - Example of using namedarray value types

using RobotRaconteur;
using System;
using System.Diagnostics;
using System.Linq;
using experimental.value_types;

using (var node_setup = new ClientNodeSetup(args))
{
    var c = (experimental.value_types.ValueTypesExample)RobotRaconteurNode.s.ConnectService(
        "rr+tcp://localhost:53223?service=values_example");

    // property MyVector3 g_vector
    c.g_vector = new MyVector3 { x = 1.0, y = 2.0, z = 3.0 };
    var b = c.g_vector;
    Debug.Assert(b.x == 4.0);
    Debug.Assert(b.y == 5.0);
    Debug.Assert(b.z == 6.0);

    // Now an array of NamedArrays
    // property MyVector3[] g_vector_array
    var f =
        new MyVector3[] { new MyVector3 { x = 1.0, y = 2.0, z = 3.0 }, new MyVector3 { x = 4.0, y = 5.0, z = 6.0 } };
    c.g_vector_array = f;

    var g = c.g_vector_array;
    Debug.Assert(g.Length == 2);
    Debug.Assert(g[0].x == 7.0);
    Debug.Assert(g[0].y == 8.0);
    Debug.Assert(g[0].z == 9.0);
    Debug.Assert(g[1].x == 10.0);
    Debug.Assert(g[1].y == 11.0);
    Debug.Assert(g[1].z == 12.0);

    // Use plain arrays and convert to and from NamedArrays
    var d = new MyVector3();
    var d1 = new ArraySegment<double>(new double[] { 1.0, 2.0, 3.0 });
    d.AssignFromNumericArray(ref d1);
    c.g_vector = d;
    var e = c.g_vector;
    var e1 = new ArraySegment<double>(new double[3]);
    e.GetNumericArray(ref e1);
    Debug.Assert(Enumerable.SequenceEqual(e1.Array, new double[] { 4.0, 5.0, 6.0 }));

    // property MyQuaternion h_quaternion
    var j = new MyQuaternion() { w = 1.0, x = 0.0, y = 0.0, z = 0.0 };
    c.h_quaternion = j;

    var k = c.h_quaternion;
    Debug.Assert(k.w == 0.707);
    Debug.Assert(k.x == 0.0);
    Debug.Assert(k.y == 0.707);
    Debug.Assert(k.z == 0.0);

    // MyPose is a composite NamedArray with fields of other NamedArrays
    // property MyPose l_pose
    var l = new MyPose() { orientation = new MyQuaternion() { w = 1.0, x = 0.0, y = 0.0, z = 0.0 },
                           position = new MyVector3() { x = 1.0, y = 2.0, z = 3.0 } };

    c.i_pose = l;

    var m = c.i_pose;
    Debug.Assert(m.position.x == 4.0);
    Debug.Assert(m.position.y == 5.0);
    Debug.Assert(m.position.z == 6.0);
    Debug.Assert(m.orientation.w == 0.707);
    Debug.Assert(m.orientation.x == 0.0);
    Debug.Assert(m.orientation.y == 0.707);
    Debug.Assert(m.orientation.z == 0.0);

    // Now use plain arrays and convert to and from NamedArrays
    var n = new MyPose();
    var n1 = new ArraySegment<double>(new double[] { 1.0, 0.0, 0.0, 0.0, 1.0, 2.0, 3.0 });
    n.AssignFromNumericArray(ref n1);
    c.i_pose = n;

    var o = c.i_pose;
    Debug.Assert(Enumerable.SequenceEqual(o.GetNumericArray(), new double[] { 0.707, 0.0, 0.707, 0.0, 4.0, 5.0, 6.0 }));
}

// namedarray_value_types.cpp - Example of using namedarray value types

#include <stdio.h>
#include <iostream>
#include <boost/range/algorithm.hpp>
#include <RobotRaconteur.h>
#include "robotraconteur_generated.h"

// Only use the RR alias in cpp files. Do not use it in header files.
namespace RR = RobotRaconteur;
namespace vt = experimental::value_types;

template <typename T>
void assert_array(const RR::RRArrayPtr<T>& a, const std::vector<T>& b)
{
    assert(a->size() == b.size());
    // RRArray supports standard C++ iterator interface.
    // The intrusive_ptr smart pointer
    // is dereferenced to access the underlying RRArray.
    assert(boost::range::equal(*a, b));
}

int main(int argc, char* argv[])
{
    RR::ClientNodeSetup node_setup(ROBOTRACONTEUR_SERVICE_TYPES, argc, argv);

    vt::ValueTypesExamplePtr c = RR::rr_cast<vt::ValueTypesExample>(
        RR::RobotRaconteurNode::s()->ConnectService("rr+tcp://localhost:53223?service=values_example"));

    // property MyVector3 g_vector
    vt::MyVector3 c1;
    c1.s.x = 1.0;
    c1.s.y = 2.0;
    c1.s.z = 3.0;
    c->set_g_vector(c1);
    vt::MyVector3 b = c->get_g_vector();
    assert(b.s.x == 4.0);
    assert(b.s.y == 5.0);
    assert(b.s.z == 6.0);

    // Now an array of NamedArrays
    // property MyVector3[] g_vector_array
    RR::RRNamedArrayPtr<vt::MyVector3> f = RR::AllocateEmptyRRNamedArray<vt::MyVector3>(2);
    f->at(0).s.x = 1.0;
    f->at(0).s.y = 2.0;
    f->at(0).s.z = 3.0;
    f->at(1).s.x = 4.0;
    f->at(1).s.y = 5.0;
    f->at(1).s.z = 6.0;

    c->set_g_vector_array(f);

    RR::RRNamedArrayPtr<vt::MyVector3> g = c->get_g_vector_array();
    assert(g->size() == 2);
    assert(g->at(0).s.x == 7.0);
    assert(g->at(0).s.y == 8.0);
    assert(g->at(0).s.z == 9.0);
    assert(g->at(1).s.x == 10.0);
    assert(g->at(1).s.y == 11.0);
    assert(g->at(1).s.z == 12.0);

    // Use plain arrays and convert to and from NamedArrays
    vt::MyVector3 d;
    // d.a has type double[3]
    d.a[0] = 1.0;
    d.a[1] = 2.0;
    d.a[2] = 3.0;
    c->set_g_vector(d);
    vt::MyVector3 e = c->get_g_vector();
    assert(e.a[0] == 4.0);
    assert(e.a[1] == 5.0);
    assert(e.a[2] == 6.0);

    // property MyQuaternion h_quaternion
    vt::MyQuaternion j;
    j.s.w = 1.0;
    j.s.x = 0.0;
    j.s.y = 0.0;
    j.s.z = 0.0;

    c->set_h_quaternion(j);

    vt::MyQuaternion k = c->get_h_quaternion();
    assert(k.s.w == 0.707);
    assert(k.s.x == 0.0);
    assert(k.s.y == 0.707);
    assert(k.s.z == 0.0);

    // MyPose is a composite NamedArray with fields of other NamedArrays
    // property MyPose l_pose
    vt::MyPose l;
    l.s.orientation.s.w = 1.0;
    l.s.orientation.s.x = 0.0;
    l.s.orientation.s.y = 0.0;
    l.s.orientation.s.z = 0.0;
    l.s.position.s.x = 1.0;
    l.s.position.s.y = 2.0;
    l.s.position.s.z = 3.0;

    c->set_i_pose(l);

    vt::MyPose m = c->get_i_pose();
    assert(m.s.position.s.x == 4.0);
    assert(m.s.position.s.y == 5.0);
    assert(m.s.position.s.z == 6.0);
    assert(m.s.orientation.s.w == 0.707);
    assert(m.s.orientation.s.x == 0.0);
    assert(m.s.orientation.s.y == 0.707);
    assert(m.s.orientation.s.z == 0.0);

    // Now use plain arrays and convert to and from NamedArrays
    double n1[] = {1.0, 0.0, 0.0, 0.0, 1.0, 2.0, 3.0};
    vt::MyPose n;
    memcpy(&n.a[0], n1, sizeof(vt::MyPose));
    c->set_i_pose(n);

    vt::MyPose o = c->get_i_pose();
    double o1[]{0.707, 0.0, 0.707, 0.0, 4.0, 5.0, 6.0};
    assert(memcmp(&o.a[0], o1, sizeof(vt::MyPose)) == 0);

    std::cout << "namedarray_value_types.cpp example complete" << std::endl;
    return 0;
}

Container Types

Robot Raconteur containers store a collection of values using lists and maps. The available container types are list, map{int32}, and map{string}. The container types can store any value type, except for other containers. Containers are nullable.

The following members from the experimental.value_types.ValueTypesExample object are used in the examples for container types:

    # Container examples
    # Containers can be int32 key maps, string key maps, or lists
    # All types can be stored in containers, but containers cannot
    # directly contain other containers. For example
    # string{list} is allowed, but string{list}{list} is not.
    property double{int32} l_double_map
    property double[]{string} l_double_array_map
    property string{list} m_string_list
    property string{int32} m_string_map_int32
    property string{string} m_string_map_string
    property MyVector3{int32} n_vector_map
    property MyStructure{list} o_struct_list

The examples below show how to use containers in Python, MATLAB, LabView, C#, and C++.

# container_value_types.py - Example of using container value types (maps and lists)

from RobotRaconteur.Client import *
import numpy as np

c = RRN.ConnectService('rr+tcp://localhost:53223?service=values_example')

# property double{int32} l_double_map
# int32 keyed map of scalar doubles
c.l_double_map = {
    1: 1.1,
    2: 2.2,
    5: 3.3
}

b = c.l_double_map
assert (len(b) == 2)
assert (b[1] == 5.1)
assert (b[5] == 6.2)

# property double[]{string} l_double_array_map
# string keyed map of double arrays
c.l_double_array_map = {
    "key1": np.array([1.1, 1.2, 1.3], dtype=np.float64),
    "key2": np.array([2.1, 2.2, 2.3], dtype=np.float64)
}

d = c.l_double_array_map
assert (len(d) == 2)
np.testing.assert_array_equal(d["key3"], [5.1, 5.2, 5.3])
np.testing.assert_array_equal(d["key4"], [6.1, 6.2, 6.3])

# property string{list} m_string_list
# list of strings
c.m_string_list = ["string 1", "string 2", "string 3"]

a = c.m_string_list
assert (len(a) == 2)
assert (a[0] == "string 4")
assert (a[1] == "string 5")


# property string{int32} m_string_map_int32
# int32 keyed map of strings
c.m_string_map_int32 = {
    12: "string 1",
    100: "string 2",
    17: "string 3"
}

e = c.m_string_map_int32
assert (len(e) == 2)
assert (e[87] == "string 4")
assert (e[1] == "string 5")

# property string{string} m_string_map_string
# string keyed map of strings
c.m_string_map_string = {
    "key1": "string 1",
    "key2": "string 2"
}

f = c.m_string_map_string
assert (len(f) == 3)
assert (f["key3"] == "string 3")
assert (f["key4"] == "string 4")
assert (f["key5"] == "string 5")

# property MyVector3{int32} n_vector_map
# int32 keyed map of MyVector3
my_vector3_dtype = RRN.GetNamedArrayDType("experimental.value_types.MyVector3", obj=c)
e = np.zeros((1,), dtype=my_vector3_dtype)
e[0]["x"] = 1.0
e[0]["y"] = 2.0
e[0]["z"] = 3.0
c.n_vector_map = {
    1: e
}

g = c.n_vector_map
assert (len(g) == 1)
g1 = g[1]
assert (g1[0]["x"] == 4.0)
assert (g1[0]["y"] == 5.0)
assert (g1[0]["z"] == 6.0)

# property MyStructure{list} o_struct_list
# list of MyStructure
my_structure_type = RRN.GetStructureType("experimental.value_types.MyStructure", obj=c)
h = my_structure_type()
h.a = 5
h.b = np.array([10, 20], dtype=np.uint32)
h.c = "String from structure client"
h.d = [
    "string a",
    "string b"
]
c.o_struct_list = [h]

i = c.o_struct_list
assert (len(i) == 1)
i0 = i[0]
assert (i0.a == 52)
np.testing.assert_array_equal(i[0].b, np.array([110, 120], dtype=np.uint32))
assert (i0.c == "String from structure service")
assert (len(i[0].d) == 3)
assert (i0.d[0] == "string c")
assert (i0.d[1] == "string d")
assert (i0.d[2] == "string e")

% container_value_types.m - Example of using container value types (maps and lists)

c = RobotRaconteur.ConnectService('rr+tcp://localhost:53223?service=values_example');

% property double{int32} l_double_map
% int32 keyed map of scalar doubles
% Robot Raconteur Matlab uses containers.Map to store maps
c.l_double_map = containers.Map(   ...
    {int32(1), int32(2),           ...
    int32(5)},{1.1, 2.2, 3.3}      ...
);

b = c.l_double_map;
assert (length(b) == 2)
assert (b(1) == 5.1)
assert (b(5) == 6.2)

% property double[]{string} l_double_array_map
% string keyed map of double arrays
c.l_double_array_map = containers.Map(     ...
    {'key1', 'key2'},                      ...
    {[1.1, 1.2, 1.3]', [2.1, 2.2, 2.3]'}      ...
);

d = c.l_double_array_map;
assert (length(d) == 2)
assert(isequal(d('key3'), [5.1, 5.2, 5.3]'));
assert(isequal(d('key4'), [6.1, 6.2, 6.3]'));

% property string{list} m_string_list
% list of strings
% Robot Raconteur Matlab uses column cell arrays to store lists
c.m_string_list = {'string 1', 'string 2', 'string 3'}';

a = c.m_string_list;
assert (length(a) == 2);
assert (strcmp(a{1}, 'string 4'));
assert (strcmp(a{2}, 'string 5'));


% property string{int32} m_string_map_int32
% int32 keyed map of strings
c.m_string_map_int32 = containers.Map(    ...
    {int32(12), int32(100), int32(17)},   ...
    {'string 1', 'string 2', 'string 3'}  ...
);

e = c.m_string_map_int32;
assert (length(e) == 2)
assert (strcmp(e(87), 'string 4'));
assert (strcmp(e(1), 'string 5'));

% property string{string} m_string_map_string
% string keyed map of strings
c.m_string_map_string = containers.Map(   ...
    {'key1', 'key2'},                     ...
    {'string 1', 'string 2'}              ...
);

f = c.m_string_map_string;
assert (length(f) == 3)
assert (strcmp(f('key3'), 'string 3'));
assert (strcmp(f('key4'), 'string 4'));
assert (strcmp(f('key5'), 'string 5'));

% property MyVector3{int32} n_vector_map
% int32 keyed map of MyVector3
e = [1.0, 2.0, 3.0]';
c.n_vector_map = containers.Map({int32(1)}, {e});

g = c.n_vector_map;
assert (length(g) == 1);
assert(isequal(g(1), [4.0, 5.0, 6.0]'));

% property MyStructure{list} o_struct_list
% list of MyStructure
h = RobotRaconteur.CreateStructure(c, "experimental.value_types.MyStructure");
h.a = 5;
h.b = uint32([10, 20]');
h.c = 'String from structure client';
h.d = {'string a', 'string b'}';
c.o_struct_list = {h};

i = c.o_struct_list;
assert (length(i) == 1)
i0 = i{1};
assert(i0.a == 52)
assert(isequal(i0.b, [110, 120]'))
assert(strcmp(i0.c, 'String from structure service'));
assert(length(i0.d) == 3);
assert(strcmp(i0.d{1}, 'string c'));
assert(strcmp(i0.d{2}, 'string d'));
assert(strcmp(i0.d{3}, 'string e'));

RobotRaconteur.DisconnectService(c);

// container_value_types.cs - Example of using container value types (maps and lists)

using RobotRaconteur;
using System;
using System.Diagnostics;
using System.Linq;
using System.Collections.Generic;
using experimental.value_types;

using (var node_setup = new ClientNodeSetup(args))
{
    var c = (experimental.value_types.ValueTypesExample)RobotRaconteurNode.s.ConnectService(
        "rr+tcp://localhost:53223?service=values_example");

    // property double{int32} l_double_map
    // int32 keyed map of scalar doubles
    c.l_double_map = new Dictionary<int, double>() { { 1, 1.1 }, { 2, 2.2 }, { 5, 3.3 } };

    var b = c.l_double_map;
    Debug.Assert(b.Count == 2);
    Debug.Assert(b[1] == 5.1);
    Debug.Assert(b[5] == 6.2);

    // property double[]{string} l_double_array_map
    // string keyed map of double arrays
    c.l_double_array_map = new Dictionary<string, double[]>() { { "key1", new double[] { 1.1, 1.2, 1.3 } },
                                                                { "key2", new double[] { 2.1, 2.2, 2.3 } } };

    var d = c.l_double_array_map;
    Debug.Assert(d.Count == 2);
    Debug.Assert(d["key3"].SequenceEqual(new double[] { 5.1, 5.2, 5.3 }));
    Debug.Assert(d["key4"].SequenceEqual(new double[] { 6.1, 6.2, 6.3 }));

    // property string{list} m_string_list
    // list of strings
    c.m_string_list = new List<string>() { "string 1", "string 2", "string 3" };

    var a = c.m_string_list;
    Debug.Assert(a.Count == 2);
    Debug.Assert(a[0] == "string 4");
    Debug.Assert(a[1] == "string 5");

    // property string{int32} m_string_map_int32
    // int32 keyed map of strings
    c.m_string_map_int32 =
        new Dictionary<int, string>() { { 12, "string 1" }, { 100, "string 2" }, { 17, "string 3" } };

    var e = c.m_string_map_int32;
    Debug.Assert(e.Count == 2);
    Debug.Assert(e[87] == "string 4");
    Debug.Assert(e[1] == "string 5");

    // property string{string} m_string_map_string
    // string keyed map of strings
    c.m_string_map_string = new Dictionary<string, string>() { { "key1", "string 1" }, { "key2", "string 2" } };

    var f = c.m_string_map_string;
    Debug.Assert(f.Count == 3);
    Debug.Assert(f["key3"] == "string 3");
    Debug.Assert(f["key4"] == "string 4");
    Debug.Assert(f["key5"] == "string 5");

    // property MyVector3{int32} n_vector_map
    // int32 keyed map of MyVector3
    var g = new MyVector3() { x = 1.0, y = 2.0, z = 3.0 };
    c.n_vector_map = new Dictionary<int, MyVector3>() { { 1, g } };

    var g1 = c.n_vector_map;
    Debug.Assert(g1.Count == 1);
    Debug.Assert(g1[1].x == 4.0);
    Debug.Assert(g1[1].y == 5.0);
    Debug.Assert(g1[1].z == 6.0);

    // property MyStructure{list} o_struct_list
    // list of MyStructure
    var h = new MyStructure() { a = 5, b = new uint[] { 10, 20 }, c = "String from structure client",
                                d = new List<string>() { "string a", "string b" } };
    c.o_struct_list = new List<MyStructure>() { h };

    var i = c.o_struct_list;
    Debug.Assert(i.Count == 1);
    Debug.Assert(i[0].a == 52);
    Debug.Assert(Enumerable.SequenceEqual(i[0].b, new uint[] { 110, 120 }));
    Debug.Assert(i[0].c == "String from structure service");
    Debug.Assert(Enumerable.SequenceEqual(i[0].d, new List<string>() { "string c", "string d", "string e" }));
}

// container_value_types.cpp - Example of using container value types (maps and lists)

#include <stdio.h>
#include <iostream>
#include <boost/range/algorithm.hpp>
#include <RobotRaconteur.h>
#include "robotraconteur_generated.h"

// Only use the RR alias in cpp files. Do not use it in header files.
namespace RR = RobotRaconteur;
namespace vt = experimental::value_types;

template <typename T>
void assert_array(const RR::RRArrayPtr<T>& a, const std::vector<T>& b)
{
    assert(a->size() == b.size());
    // RRArray supports standard C++ iterator interface.
    // The intrusive_ptr smart pointer
    // is dereferenced to access the underlying RRArray.
    assert(boost::range::equal(*a, b));
}

int main(int argc, char* argv[])
{
    RR::ClientNodeSetup node_setup(ROBOTRACONTEUR_SERVICE_TYPES, argc, argv);

    vt::ValueTypesExamplePtr c = RR::rr_cast<vt::ValueTypesExample>(
        RR::RobotRaconteurNode::s()->ConnectService("rr+tcp://localhost:53223?service=values_example"));

    // property double{int32} l_double_map
    // int32 keyed map of scalar doubles
    RR::RRMapPtr<int32_t, RR::RRArray<double> > l_double_map1 = RR::AllocateEmptyRRMap<int32_t, RR::RRArray<double> >();
    l_double_map1->insert(std::make_pair(1, RR::ScalarToRRArray<double>(1.1)));
    l_double_map1->insert(std::make_pair(2, RR::ScalarToRRArray<double>(2.2)));
    l_double_map1->insert(std::make_pair(5, RR::ScalarToRRArray<double>(3.3)));
    c->set_l_double_map(l_double_map1);

    RR::RRMapPtr<int32_t, RR::RRArray<double> > b = c->get_l_double_map();
    // Containers can be null
    RR::rr_null_check(b);
    assert(b->size() == 2);
    // Container elements can be null
    RR::rr_null_check(b->at(1));
    RR::rr_null_check(b->at(5));
    assert_array(b->at(1), {5.1});
    assert_array(b->at(5), {6.2});

    // property double[]{string} l_double_array_map
    // string keyed map of double arrays
    RR::RRMapPtr<std::string, RR::RRArray<double> > l_double_array_map1 =
        RR::AllocateEmptyRRMap<std::string, RR::RRArray<double> >();
    l_double_array_map1->insert(std::make_pair("key1", RR::VectorToRRArray<double, double>({1.1, 1.2, 1.3})));
    l_double_array_map1->insert(std::make_pair("key2", RR::VectorToRRArray<double, double>({2.1, 2.2, 2.3})));
    c->set_l_double_array_map(l_double_array_map1);

    RR::RRMapPtr<std::string, RR::RRArray<double> > l_double_array_map2 = c->get_l_double_array_map();
    RR::rr_null_check(l_double_array_map2);
    assert(l_double_array_map2->size() == 2);
    RR::rr_null_check(l_double_array_map2->at("key3"));
    RR::rr_null_check(l_double_array_map2->at("key4"));
    assert_array(l_double_array_map2->at("key3"), {5.1, 5.2, 5.3});
    assert_array(l_double_array_map2->at("key4"), {6.1, 6.2, 6.3});

    // property string{list} m_string_list
    // list of strings
    RR::RRListPtr<RR::RRArray<char> > m_string_list1 = RR::AllocateEmptyRRList<RR::RRArray<char> >();
    m_string_list1->push_back(RR::stringToRRArray("string 1"));
    m_string_list1->push_back(RR::stringToRRArray("string 2"));
    m_string_list1->push_back(RR::stringToRRArray("string 3"));
    c->set_m_string_list(m_string_list1);

    RR::RRListPtr<RR::RRArray<char> > a = c->get_m_string_list();
    // Containers can be null
    RR::rr_null_check(a);
    assert(a->size() == 2);
    // Container elements can be null
    auto a_iterator = a->begin();
    RR::rr_null_check(*a_iterator);
    assert(RR::RRArrayToString(*a_iterator++) == "string 4");
    RR::rr_null_check(*a_iterator);
    assert(RR::RRArrayToString(*a_iterator++) == "string 5");

    // property string{int32} m_string_map_int32
    // int32 keyed map of strings
    RR::RRMapPtr<int32_t, RR::RRArray<char> > m_string_map_int32_1 =
        RR::AllocateEmptyRRMap<int32_t, RR::RRArray<char> >();
    m_string_map_int32_1->insert(std::make_pair(12, RR::stringToRRArray("string 1")));
    m_string_map_int32_1->insert(std::make_pair(100, RR::stringToRRArray("string 2")));
    m_string_map_int32_1->insert(std::make_pair(17, RR::stringToRRArray("string 3")));
    c->set_m_string_map_int32(m_string_map_int32_1);

    RR::RRMapPtr<int32_t, RR::RRArray<char> > e = c->get_m_string_map_int32();
    // Containers can be null
    RR::rr_null_check(e);
    assert(e->size() == 2);
    // Container elements can be null
    RR::rr_null_check(e->at(87));
    RR::rr_null_check(e->at(1));
    assert(RR::RRArrayToString(e->at(87)) == "string 4");
    assert(RR::RRArrayToString(e->at(1)) == "string 5");

    // property string{string} m_string_map_string
    // string keyed map of strings
    RR::RRMapPtr<std::string, RR::RRArray<char> > m_string_map_string_1 =
        RR::AllocateEmptyRRMap<std::string, RR::RRArray<char> >();
    m_string_map_string_1->insert(std::make_pair("key1", RR::stringToRRArray("string 1")));
    m_string_map_string_1->insert(std::make_pair("key2", RR::stringToRRArray("string 2")));
    c->set_m_string_map_string(m_string_map_string_1);

    RR::RRMapPtr<std::string, RR::RRArray<char> > f = c->get_m_string_map_string();
    // Containers can be null
    RR::rr_null_check(f);
    assert(f->size() == 3);
    // Container elements can be null
    RR::rr_null_check(f->at("key3"));
    RR::rr_null_check(f->at("key4"));
    RR::rr_null_check(f->at("key5"));
    assert(RR::RRArrayToString(f->at("key3")) == "string 3");
    assert(RR::RRArrayToString(f->at("key4")) == "string 4");
    assert(RR::RRArrayToString(f->at("key5")) == "string 5");

    // property MyVector3{int32} n_vector_map
    // int32 keyed map of MyVector3
    vt::MyVector3 g; // = new MyVector3() { x = 1.0, y = 2.0, z = 3.0 };
    g.s.x = 1.0;
    g.s.y = 2.0;
    g.s.z = 3.0;
    RR::RRMapPtr<int32_t, RR::RRNamedArray<vt::MyVector3> > n_vector_map_1 =
        RR::AllocateEmptyRRMap<int32_t, RR::RRNamedArray<vt::MyVector3> >();
    n_vector_map_1->insert(std::make_pair(1, RR::ScalarToRRNamedArray(g)));
    c->set_n_vector_map(n_vector_map_1);

    RR::RRMapPtr<int32_t, RR::RRNamedArray<vt::MyVector3> > g1 = c->get_n_vector_map();
    // Containers can be null
    RR::rr_null_check(g1);
    assert(g1->size() == 1);
    // Container elements can be null
    RR::rr_null_check(g1->at(1));
    vt::MyVector3 g2 = RR::RRNamedArrayToScalar(g1->at(1));
    assert(g2.s.x == 4.0);
    assert(g2.s.y == 5.0);
    assert(g2.s.z == 6.0);

    // property MyStructure{list} o_struct_list
    // list of MyStructure
    vt::MyStructurePtr h1(new vt::MyStructure());
    h1->a = 5;
    h1->b = RR::VectorToRRArray<uint32_t, uint32_t>({10, 20});
    h1->c = "String from structure client";
    RR::RRListPtr<RR::RRArray<char> > h1_d = RR::AllocateEmptyRRList<RR::RRArray<char> >();
    h1_d->push_back(RR::stringToRRArray("string a"));
    h1_d->push_back(RR::stringToRRArray("string b"));
    h1->d = h1_d;
    RR::RRListPtr<vt::MyStructure> h2 = RR::AllocateEmptyRRList<vt::MyStructure>();
    h2->push_back(h1);
    c->set_o_struct_list(h2);

    RR::RRListPtr<vt::MyStructure> i = c->get_o_struct_list();
    // Containers can be null
    RR::rr_null_check(i);
    assert(i->size() == 1);
    // Container elements can be null
    RR::rr_null_check(*(i->begin()));
    vt::MyStructurePtr i0 = *(i->begin());
    assert(i0->a == 52);
    assert_array(i0->b, {110, 120});
    assert(i0->c == "String from structure service");
    // Containers can be null
    RR::rr_null_check(i0->d);
    assert(i0->d->size() == 3);
    auto i0_d_iterator = i0->d->begin();
    assert(RR::RRArrayToString(*i0_d_iterator++) == "string c");
    assert(RR::RRArrayToString(*i0_d_iterator++) == "string d");
    assert(RR::RRArrayToString(*i0_d_iterator++) == "string e");

    std::cout << "container_value_types.cpp example complete" << std::endl;
    return 0;
}

varvalue Type

Varvalue is a special type that can store any value type, and is a form of variant. See the language documentation for more details on how the variant is implemented in each language. The varvalue type is nullable.

The following members from the experimental.value_types.ValueTypesExample object are used in the examples for varvalue types:

    # varvalue examples
    property varvalue p_varvalue_double_array
    property varvalue q_varvalue_string
    property varvalue r_varvalue_struct
    # varvalue{string} is a string keyed map of varvalues
    # It is frequently used for "extended" fields
    # to allow for forward compatibility
    property varvalue{string} s_varvalue_map2

The examples below show how to use varvalue in Python, MATLAB, LabView, C#, and C++.

# varvalue_value_types.py - Example of using varvalue wildcard type

from RobotRaconteur.Client import *
import numpy as np

c = RRN.ConnectService('rr+tcp://localhost:53223?service=values_example')

# Any valid Robot Raconteur data type can be stored in a varvalue
# In Python, the RR.VarValue() Python structure is used to store
# the value and type of the data. The type is stored as a string.
# This is necessary because Python does not carry enough type
# information

# property varvalue p_varvalue_double_array
# Example of storing a double array in a varvalue
a = np.array([1.1, 2.2, 3.3], dtype=np.float64)
c.p_varvalue_double_array = RR.VarValue(a, "double[]")
b = c.p_varvalue_double_array
np.testing.assert_array_equal(b.data, [1.4, 2.5, 3.6])
assert b.datatype == "double[]"

# property varvalue q_varvalue_string
# Example of storing a string in a varvalue
c.q_varvalue_string = RR.VarValue("varvalue string from client", "string")
d = c.q_varvalue_string
assert d.data == "varvalue string from service"
assert d.datatype == "string"

# property varvalue r_varvalue_struct
# Example of storing a structure in a varvalue
my_structure_type = RRN.GetStructureType("experimental.value_types.MyStructure", obj=c)
s = my_structure_type()
s.a = 5
s.b = np.array([10, 20], dtype=np.uint32)
s.c = "String from structure client"
s.d = [
    "string a",
    "string b"
]

c.r_varvalue_struct = RR.VarValue(s, "experimental.value_types.MyStructure")

t = c.r_varvalue_struct
t_data = t.data

assert t_data.a == 52
np.testing.assert_array_equal(t_data.b, np.array([110, 120], dtype=np.uint32))
assert t_data.c == "String from structure service"
assert len(t_data.d) == 3
assert t_data.d[0] == "string c"
assert t_data.d[1] == "string d"
assert t_data.d[2] == "string e"

# property varvalue{string} s_varvalue_map2
# Example of storing a map of strings in a varvalue
# varvalue{string} is used extensively in structures
# to allow for additional fields to be added to the
# structure without changing the structure definition
c.s_varvalue_map2 = {
    "key1": RR.VarValue(np.array([2, 3]), "int32[]"),
    "key2": RR.VarValue("string 2", "string")
}

u = c.s_varvalue_map2
assert len(u) == 2
np.testing.assert_array_equal(u["key3"].data, [4, 5])
assert u["key3"].datatype == "int32[]"
assert u["key4"].data == "string 4"
assert u["key4"].datatype == "string"

% varvalue_value_types.m - Example of using varvalue wildcard type

c = RobotRaconteur.ConnectService('rr+tcp://localhost:53223?service=values_example');

% Any valid Robot Raconteur data type can be stored in a varvalue
% In Matlab, the RobotRaconteurVarValue() class is used to store
% the value and type of the data. The type is stored as a string.
% This is necessary because Matlab does not carry enough type
% information

% property varvalue p_varvalue_double_array
% Example of storing a double array in a varvalue
a = [1.1, 2.2, 3.3]';
c.p_varvalue_double_array = RobotRaconteurVarValue(a, "double[]");
b = c.p_varvalue_double_array;
assert(isequal(b.data, [1.4, 2.5, 3.6]'));
assert(strcmp(b.datatype, "double[]"));

% property varvalue q_varvalue_string
% Example of storing a string in a varvalue
c.q_varvalue_string = RobotRaconteurVarValue('varvalue string from client', 'string');
d = c.q_varvalue_string;
assert(strcmp(d.data, 'varvalue string from service'));
assert(strcmp(d.datatype, 'string'));

% property varvalue r_varvalue_struct
% Example of storing a structure in a varvalue
s = RobotRaconteur.CreateStructure(c, 'experimental.value_types.MyStructure');
s.a = 5;
s.b = uint32([10, 20]');
s.c = 'String from structure client';
s.d = {'string a', 'string b'}';

c.r_varvalue_struct = RobotRaconteurVarValue(s, "experimental.value_types.MyStructure");

t = c.r_varvalue_struct;
t_data = t.data;

assert(t_data.a == 52);
assert(isequal(t_data.b, [110, 120]'));
assert(strcmp(t_data.c, 'String from structure service'));
assert(length(t_data.d) == 3);
assert(strcmp(t_data.d{1}, "string c"));
assert(strcmp(t_data.d{2}, "string d"));
assert(strcmp(t_data.d{3}, 'string e'));

% property varvalue{string} s_varvalue_map2
% Example of storing a map of strings in a varvalue
% varvalue{string} is used extensively in structures
% to allow for additional fields to be added to the
% structure without changing the structure definition
c.s_varvalue_map2 = containers.Map(                       ...
    {'key1', 'key2'},                                     ...
    { RobotRaconteurVarValue(int32([2, 3]'), 'int32[]'), ...
      RobotRaconteurVarValue('string 2', 'string')}       ...
);

u = c.s_varvalue_map2;
assert(length(u) == 2)
assert(isequal(u('key3').data, [4, 5]'));
assert(strcmp(u('key3').datatype, 'int32[]'));
assert(strcmp(u('key4').data, 'string 4'));
assert(strcmp(u('key4').datatype, 'string'));

RobotRaconteur.DisconnectService(c);

// varvalue_value_types.cs - Example of using varvalue wildcard type

using RobotRaconteur;
using System;
using System.Diagnostics;
using System.Linq;
using System.Collections.Generic;
using experimental.value_types;

using (var node_setup = new ClientNodeSetup(args))
{
    var c = (experimental.value_types.ValueTypesExample)RobotRaconteurNode.s.ConnectService(
        "rr+tcp://localhost:53223?service=values_example");

    // Any valid Robot Raconteur data type can be stored in a varvalue

    // property varvalue p_varvalue_double_array
    // Example of storing a double array in a varvalue
    var a = new double[] { 1.1, 2.2, 3.3 };
    c.p_varvalue_double_array = a;
    var b = (double[])c.p_varvalue_double_array;
    Debug.Assert(Enumerable.SequenceEqual(b, new double[] { 1.4, 2.5, 3.6 }));

    // property varvalue q_varvalue_string
    // Example of storing a string in a varvalue
    c.q_varvalue_string = "varvalue string from client";
    var d = (string)c.q_varvalue_string;
    Debug.Assert(d == "varvalue string from service");

    // property varvalue r_varvalue_struct
    // Example of storing a structure in a varvalue
    var s = new MyStructure() { a = 5, b = new uint[] { 10, 20 }, c = "String from structure client",
                                d = new List<string>() { "string a", "string b" } };

    c.r_varvalue_struct = s;

    var t = (MyStructure)c.r_varvalue_struct;
    Debug.Assert(t.a == 52);
    Debug.Assert(Enumerable.SequenceEqual(t.b, new uint[] { 110, 120 }));
    Debug.Assert(t.c == "String from structure service");
    Debug.Assert(Enumerable.SequenceEqual(t.d, new List<string>() { "string c", "string d", "string e" }));

    // property varvalue{string} s_varvalue_map2
    // Example of storing a map of strings in a varvalue
    // varvalue{string} is used extensively in structures
    // to allow for additional fields to be added to the
    // structure without changing the structure definition
    c.s_varvalue_map2 = new Dictionary<string, object>() { { "key1", new int[] { 2, 3 } }, { "key2", "string 2" } };

    var u = c.s_varvalue_map2;
    Debug.Assert(u.Count == 2);
    Debug.Assert(Enumerable.SequenceEqual((int[])u["key3"], new int[] { 4, 5 }));
    Debug.Assert((string)u["key4"] == "string 4");
}

// numeric_value_types.cpp - Example of using numeric value types

#include <stdio.h>
#include <iostream>
#include <boost/range/algorithm.hpp>
#include <RobotRaconteur.h>
#include "robotraconteur_generated.h"

// Only use the RR alias in cpp files. Do not use it in header files.
namespace RR = RobotRaconteur;
namespace vt = experimental::value_types;

template <typename T>
void assert_array(const RR::RRArrayPtr<T>& a, const std::vector<T>& b)
{
    assert(a->size() == b.size());
    // RRArray supports standard C++ iterator interface.
    // The intrusive_ptr smart pointer
    // is dereferenced to access the underlying RRArray.
    assert(boost::range::equal(*a, b));
}

int main(int argc, char* argv[])
{
    RR::ClientNodeSetup node_setup(ROBOTRACONTEUR_SERVICE_TYPES, argc, argv);

    vt::ValueTypesExamplePtr c = RR::rr_cast<vt::ValueTypesExample>(
        RR::RobotRaconteurNode::s()->ConnectService("rr+tcp://localhost:53223?service=values_example"));

    // Scalar numbers
    // property double a_double
    double a_double_read = c->get_a_double();
    std::cout << a_double_read << std::endl;
    // assert used for the rest of the example property read operations
    // to demonstrate the expected values.
    assert(c->get_a_double() == 5.78);
    c->set_a_double(49.3);
    // property int32 b_int
    assert(c->get_b_int() == 4557);
    c->set_b_int(359);
    // property uint8 c_byte
    assert(c->get_c_byte() == 0x1A);
    c->set_c_byte(31);
    // property cdouble d_cdouble
    assert(c->get_d_cdouble() == RR::cdouble(23.7, 5.3));
    c->set_d_cdouble(RR::cdouble(1.2, 3.4));
    // property bool e_bool
    // RR::rr_bool is used for Robot Raconteur bool values
    assert(c->get_e_bool().value != 0);
    c->set_e_bool(RR::rr_bool(0));
    // property int32 meaning_of_life [readonly]
    assert(c->get_meaning_of_life() == 42);

    // Numeric Arrays
    // property double[] a_double_array
    assert_array(c->get_a_double_array(), {0.016, 0.226});

    // Examples of different ways to initialize RRArray. Also see Eigen converters in robotraconteur-companion

    // Use AttachRRArrayCopy()
    double a_double_array_1a[] = {0.582, 0.288, 0.09, 0.213, 0.98};
    RR::RRArrayPtr<double> a_double_array_1 = RR::AttachRRArrayCopy(a_double_array_1a, 5);
    c->set_a_double_array(a_double_array_1);

    // Use AllocateRRArray to allocate an uninitialized array
    RR::RRArrayPtr<double> a_double_array_2 = RR::AllocateRRArray<double>(5);
    a_double_array_2->at(0) = 0.582;
    a_double_array_2->at(1) = 0.288;
    a_double_array_2->at(2) = 0.09;
    a_double_array_2->at(3) = 0.213;
    a_double_array_2->at(4) = 0.98;
    c->set_a_double_array(a_double_array_2);

    RR::RRArrayPtr<double> a_double_array_2b = c->get_a_double_array();
    assert(a_double_array_2b->size() == 2);
    assert(a_double_array_2b->at(0) == 0.016);
    assert((*a_double_array_2b)[1] == 0.226);

    // Use VectorToRRArray to convert a std::vector to RRArray
    std::vector<double> a_double_array_3a = {0.582, 0.288, 0.09, 0.213, 0.98};
    RR::RRArrayPtr<double> a_double_array_3 = RR::VectorToRRArray<double, double>(a_double_array_3a);
    c->set_a_double_array(a_double_array_3);

    // property double[3] a_double_array_fixed
    assert_array(c->get_a_double_array_fixed(), {0.13, 0.27, 0.15});
    c->set_a_double_array_fixed(RR::VectorToRRArray<double, double>({0.21, 0.12, 0.39}));
    // % property double[6-] a_double_array_maxlen
    assert_array(c->get_a_double_array_maxlen(), {0.7, 0.16, 0.16, 0.05, 0.61, 0.9});
    c->set_a_double_array_maxlen(RR::VectorToRRArray<double, double>({0.035, 0.4}));
    // property double[3,2] a_double_marray_fixed
    RR::RRMultiDimArrayPtr<double> a_double_marray_fixed_read = c->get_a_double_marray_fixed();
    assert_array(a_double_marray_fixed_read->Dims, {3, 2});
    assert_array(a_double_marray_fixed_read->Array, {0.29, 0.41, 0.4, 0.66, 0.6, 0.2});
    RR::RRMultiDimArrayPtr<double> a_double_marray_fixed_1 =
        RR::AllocateRRMultiDimArray<double>(RR::VectorToRRArray<uint32_t, uint32_t>({3, 2}),
                                            RR::VectorToRRArray<double, double>({0.3, 0.4, 0.5, 0.6, 0.6, 0.2}));
    c->set_a_double_marray_fixed(a_double_marray_fixed_1);
    // property double[*] a_double_marray
    RR::RRMultiDimArrayPtr<double> a_double_marray_read = c->get_a_double_marray();
    assert_array(a_double_marray_read->Dims, {2, 2});
    assert_array(a_double_marray_read->Array, {0.72, 0.05, 0.4, 0.07});
    RR::RRMultiDimArrayPtr<double> a_double_marray_1 = RR::AllocateRRMultiDimArray<double>(
        RR::VectorToRRArray<uint32_t, uint32_t>({2, 1}), RR::VectorToRRArray<double, double>({0.3, 0.01}));
    // property uint8[] c_byte_array
    assert_array(c->get_c_byte_array(), {0x1A, 0x2B});
    c->set_c_byte_array(RR::VectorToRRArray<uint8_t, uint8_t>({0x3C, 0x4D, 0x5E, 0x6F, 0x70}));

    std::cout << "numeric_value_types.cpp example complete" << std::endl;
    return 0;
}

Nullable Types

Structures, containers, and varvalues are nullable, meaning they can be set to null. All other value types are not nullable.

The following members from the experimental.value_types.ValueTypesExample object are used in the examples for nullable types:

    property MyStructure t_struct_null

The examples below show how to use nullable types in Python, MATLAB, LabView, C#, and C++.

# null_value_types.py - Example of types that can be null

from RobotRaconteur.Client import *
import numpy as np

c = RRN.ConnectService('rr+tcp://localhost:53223?service=values_example')

# Null values
# Null values are "None" in Python
# struct, containers, and varvalue are nullable.
# Numbers, arrays, strings, pods, and namedarrays are not nullable.

# property MyStructure t_struct_null
c.t_struct_null = None
assert c.t_struct_null is None

% null_value_types.m - Example of types that can be null

c = RobotRaconteur.ConnectService('rr+tcp://localhost:53223?service=values_example');

% Null values
% Null values are "missing" in Matlab
% struct, containers, and varvalue are nullable.
% Numbers, arrays, strings, pods, and namedarrays are not nullable.

% property MyStructure t_struct_null
c.t_struct_null = missing;
assert(ismissing(c.t_struct_null));

RobotRaconteur.DisconnectService(c);

// null_value_types.cs - Example of types that can be null

using RobotRaconteur;
using System;
using System.Diagnostics;
using System.Linq;
using System.Collections.Generic;

using (var node_setup = new ClientNodeSetup(args))
{
    var c = (experimental.value_types.ValueTypesExample)RobotRaconteurNode.s.ConnectService(
        "rr+tcp://localhost:53223?service=values_example");

    // Null values
    // Null values are "null" in C#
    // struct, containers, and varvalue are nullable.
    // Numbers, arrays, strings, pods, and namedarrays are not nullable.

    // property MyStructure t_struct_null
    c.t_struct_null = null;
    Debug.Assert(c.t_struct_null == null);
}

// null_value_types.cpp - Example of types that can be null

#include <stdio.h>
#include <iostream>
#include <boost/range/algorithm.hpp>
#include <RobotRaconteur.h>
#include "robotraconteur_generated.h"

// Only use the RR alias in cpp files. Do not use it in header files.
namespace RR = RobotRaconteur;
namespace vt = experimental::value_types;

int main(int argc, char* argv[])
{
    RR::ClientNodeSetup node_setup(ROBOTRACONTEUR_SERVICE_TYPES, argc, argv);

    vt::ValueTypesExamplePtr c = RR::rr_cast<vt::ValueTypesExample>(
        RR::RobotRaconteurNode::s()->ConnectService("rr+tcp://localhost:53223?service=values_example"));

    // Null values
    // Null values are "nullptr" or empty intrusive_ptr
    // struct, containers, and varvalue are nullable.
    // Numbers, arrays, strings, pods, and namedarrays are not nullable.

    // property MyStructure t_struct_null
    vt::MyStructurePtr s = nullptr;
    c->set_t_struct_null(s);
    assert(c->get_t_struct_null() == nullptr);
}