Data Type Details

shared_ptr

The shared_ptr data type which is available in WinCC OA can be used like a template.

shared_ptr<int> object1;

Creates a shared_ptr object with the name object1 that points to a new object of the named data type. To create such an object, use the "new" expression.

shared_ptr<Base> object1 = new Base;

In this case <Base> is a new class. The data type used for the shared_ptr can either be a user-defined type (class/struct/enum) or also a standard data type like int, float, etc.

shared_ptr<int> object1 = new int;

You can assign the shared_ptr to another shared_ptr of the same (or compatible) type.

shared_ptr<Base> object2 = object1;

Thus, two pointers pointing at the one and only Base instance. When object1 gets out of scope (or the nullptr is assigned to it), object2 still has the pointer to the instance until it gets out of scope as well.

int foo(shared_ptr<int> &ref_to_ptr)

You can also use the void datatype, which creates a pointer which can point to any other data type.

shared_ptr<void> p = new string;

Downcasting of a shared_ptr is also allowed:

Classes B is inherited from class A

shared_ptr<A> pA = new B;
shared_ptr<B> pB;

pB = pA;

New expression

The new expression can be used with or without arguments, e.g.:

shared_ptr<int> pi = new int;                 // no argument
shared_ptr<int> pi = new int();               // no argument
shared_ptr<int> pi = new int(77);             // with initial value
shared_ptr<int> pi = new int(someFunction()); // with initial value
shared_ptr<Enum> pe = new Enum(Enum::One);    // with initial value
shared_ptr<Base> pb = new Base;               // constructor without argument
shared_ptr<Base> pb = new Base(1, 2, 3);      // constructor with arguments

A reference parameter to a shared_ptr is not possible, e.g.: int foo(shared_ptr<int> &ref_to_ptr).

You can also mimic the reference case, but only if the objects you want to shortcut are also shared_ptr instances that were created by using new. e.g.:

  mapping m;
  m[1] = new int;
  shared_ptr<int> p = m[1];
  p = 77;

  DebugN(m[1]);  => 77

Auto-dereferencing

An auto-dereferencing of shared_ptr variables is available. The auto-dereferencing is different than in C++. It works similarly to anytype/mixed since internally they also point to an instance of some other data type but when using them, they automatically get the real/final object. e.g.:

  mapping m;

  m["object"] = new Base;

  m.object.x = 88;  // not as in C++:  m.object->x = 88;

Auto-deref is always done when there is a target the pointer points at. e.g.

  shared_ptr<string> s1;               // nullptr
  shared_ptr<string> s2 = new string;  // points to a string
  s1 = s2;

The function equalPtr() can be used to compare the objects two pointers point to.

  s1 = new string;
  s2 = new string("Hello");
  s1 = s2;  /* auto-dereferencing is done.
            s1 and s2 point to different string objects
            but both strings now contain the same value "Hello" */

  equalPtr(s1, s2)  => false

  Shared_ptr<XY> spTest;

  if( spTest ) //compared with nullptr
  {
    //...
  }

Nullptr - free the memory

To free the pointed at object, just assign a nullptr to the pointer. When the last pointer pointing at an object is out of scope or a nullptr is assigned to it, the pointed at object is deleted.

  shared_ptr<string> s = new string;   // memory allocated
  s = "Hello";                         // memory written
  s = nullptr;                         // memory freed

Shape

The shape data type can hold pointers to scriptable objects.

Syntax:

shape

This data type can also be annotated with a specific shape type. For a list of available shape types see "shapeType". In addition, the names of user-generated EWOs can be used.

E.g. the user created a "UserCreated.ewo" plugin, then the string "UserCreated_ewo" is also possible.

shape<"datatype">

Using this syntax, the shape variable is only allowed to hold the specified shape type. If a different shape types is used, an exception will be thrown. As a consequence, even unassigned, the completion list for the given shape type can be shown in the script editor.

Example

Assigning a shape to the shape variable "line" within a panel containing the line "Line1" and the rectangle "Rectangle1".

  shape<"LINE"> line;
  line = Line1;        //is allowed
  line = Rectangle1;   //will throw an exception

• In contrast to shared_ptr<typeName>, the "typeName" for the shape data type is a string constant and must therefore be written including the quotation marks.
• It is possible to assign the nullptr constant. This also enables the comparison to the nullpointer constant.
• Both shape and shape<""> can hold any type of scriptable object and will not throw an exception.

Class Pointer

The class_ptr datatype is used to hold pointers to available class or struct objects. It can only contain those types.

Syntax:

class_ptr <ClassName>

A class_ptr<void> can also be used, which can point to arbitrary class objects.

The pointer is "non owning", and therefore only a "tracking" pointer.

The pointer is automatically set to nullptr when the object it points to is destroyed.

The pointer to a class object is returned by getClassPtr().

A pointer can be assigned to a class_ptr variable as long as the class_ptr variable is still null (equivalent to shared_ptr), because if it is not null, an auto-dereferencing takes place and otherwise the right side of the assignment is passed to the target object. The assignment class_ptr variable = nullptr can always be used. The pointer can also be changed with assignPtr(), even if it is already not null.

If possible, the class_ptr is auto-dereferenced.

Both assignPtr() and equalPtr() can accept class_ptr arguments.

Syntax

Application Examples

A vector holding a list of int elements:

vector<int>

The type can also be another vector:

vector< vector<int> >

Writing vector< vector<int> > is syntactically not correct, since two ">" in a row without a blank between each other are treated as a shift operator.

The elements within a vector can be addressed via their index. The index operator [] of a vector starts with 0 (ZERO). In vector the index operator can only be used for elements which are already in the vector. It is not possible to assign a value to an index that is not already present. This means that additional elements should be added with specific functions (e.g.: the member functions append() or prepend()).

  vector<int> v = makeVector(1, 2, 3, 4);

  v.append(5);    // adds element as last element
  v.prepend(0);   // adds element as first element

Vectors can only contain elements of the same defined type, meaning that a vector<int> can only hold int values. The exception to this are vector<void>, vector<anytype> and vector<mixed>. If the vector contains a class or a shared_ptr to a class, it is also possible to add derived classes (or a shared_ptr to it) to the vector.

A vector cannot be directly converted to a string. Use jsonEncode(vector) if you want to serialize the vector to a string.

Vectors & dyn data types

The functionality of a vector is comparable to the various dyn_* data types. As long as the data types are the same, a vector can be assigned to a _dyn* and vice versa. This means that a vector can also be initialized with makeDyn functions. eg.:

vector<string> v = makeDynString("a","b","c");

As a special case it is also possible to assign any vector to a dyn_anytype or a dyn_mixed.

The biggest difference between vectors and dyn_* variables is the index. For vectors this index starts at 0 while dyn_* variables start at 1. This influences, for example, the iteration with a for-loop:

vector<int> v = makeVector(1, 2, 3, 4);
for (int i = 0; i < v.count(); i++)
{
  DebugN("new value:", v[i]);
}

dyn_int dynInt = makeDynInt(1, 2, 3, 4);
for (int i = 1; i <= dynlen(dynInt); i++)
{
  DebugN("new value:", dynInt[i]);
}

vector<void>

The void data type for a vector allows to add any data type. A vector<void> is similar to a dyn_anytype, but a dyn_anytype is a dyn_ containing anytype variables, which themselves point to any other type. In terms of performance and memory consumption, the vector<void> is better, since it directly holds the final pointers to whatever datatype was given. The following function allows to create a vector<void>:

vector<void> makeVector(...)

A vector<void> can be assigned to any other vector or dyn_ as long as the datatypes of all items match the needed datatype. Otherwise an exception is thrown.

dyn_int di = makeVector(1,2,3);

vector< shared_ptr<MyObj> > myVec = makeVector(new MyObj(1), new MyObj(2), new MyObj(3));

Type alias

To make working with nested data types like vector< vector< shared_ptr<SomeClass> > > easier, the keyword "using" can be used the following way:

using AliasName = existingType

A type alias can also be used for any other type (e.g. int, vector, class, ect.). It is defined like a class declaration in a script outside of any function. The alias can then be used in the same way the full expression would be used as the parser resolves the alias name to the original type. e.g.:

using MyVec = vector < vector< shared_ptr<SomeClass> > >
using myInt = int;
using MyClass = SomeClass;
using vec_str = vector<string>;

Specific member functions are available for the vector data type.