Primitive Array API Reference

The following APIs are introduced to support primitive arrays in Event Publication Subscription:

• SetElement(element): Adds an element to a primitive array. The element can be a string or another PropertySet. For example:

  var ps = TheApplication().NewPropertySet();
  ps.SetProperty("datatype", "jsonprimarray");
  ps.SetElement("myname");
  
  var childPS = TheApplication().NewPropertySet();
  childPS.SetProperty("datatype", "jsonprimarray");
  childPS.SetElement("childElement1");
  childPS.SetElement("childElement2");
  
  ps.SetElement(childPS);
  

  In this example, the primitive array contains:

  • The string myname.
  • A nested PropertySet that contains the strings childElement1 and childElement2.
• IsNextElement(): Returns true if another element is available in the PropertySet. Otherwise, returns false. Use this method with GetNextElement().
• GetNextElement(): Returns the next string element in the PropertySet. Use this method with IsNextElement().
• IsNextElementPropertySet(): Returns true if the next element is a PropertySet. Use this method with GetNextElementAsPropertySet().
• GetNextElementAsPropertySet(): Returns the next PropertySet element. Use this method with IsNextElementPropertySet(). For example:

  var ps = TheApplication().NewPropertySet();
  var resPS = TheApplication().NewPropertySet();
  
  ps.SetProperty("datatype", "jsonprimarray");
  ps.SetElement("myname");
  
  var childPS = TheApplication().NewPropertySet();
  childPS.SetProperty("datatype", "jsonprimarray");
  childPS.SetElement("childElement1");
  childPS.SetElement("childElement2");
  
  ps.SetElement(childPS);
  
  while (ps.IsNextElement())
  {
      if (ps.IsNextElementPropertySet()) {
          resPS = ps.GetNextElementAsPropertySet();
          // do something
      }
      else
      {
          var psStr = ps.GetNextElement();
          // do something
      }
  }
  

  This example iterates through the PropertySet and processes each element according to its type.

• RemoveElement(value):Removes the first primitive element that matches the specified value. For example:

  ps.RemoveElement("string");
  ps.RemoveElement(32);
  

  Use this method for primitive values such as strings, numbers, and Boolean values. It does not remove nested PropertySet elements by value.

• RemoveElementAt(index): Removes the element at the specified zero-based position.

  ps.RemoveElementAt(1);

  This method can remove either a primitive element or a PropertySet element.

• ResetNextElementCount(): Resets sequential element reading to the beginning.
  Use this method before reading the same elements again with sequential APIs such as IsNextElement() and GetNextElement(). For example:

  while (ps.IsNextElement())
  {
      if (ps.IsNextElementPropertySet()) {
          resPS = ps.GetNextElementAsPropertySet();
          // do something
      }
      else
      {
          var psStr = ps.GetNextElement();
          // do something
      }
  }
  ps.ResetNextElementCount();
  

• GetNumberOfElements(): Returns the total number of elements in the PropertySet. For example:

  var ps = TheApplication().NewPropertySet();
  ps.SetProperty("datatype", "jsonprimarray");
  ps.SetElement("myname");
  
  var childPS = TheApplication().NewPropertySet();
  childPS.SetProperty("datatype", "jsonprimarray");
  childPS.SetElement("childElement1");
  childPS.SetElement("childElement2");
  
  ps.SetElement(childPS);
  
  var count = ps.GetNumberOfElements();
  

  In this example, ps.GetNumberOfElements() returns 2 because the PropertySet contains two elements: one string and one nested PropertySet.

• IsElementPropertySetAt(index): Returns true if the element at the specified position is a PropertySet. For example:

  if (ps.IsElementPropertySetAt(3)) {
      // ...
  }
  

  Use this method before calling GetElementAt() or GetElementAsPropertySetAt() when the element type is not known.

• GetElementAt(index): Returns the primitive element value at the specified zero-based position. For example:

  var value = ps.GetElementAt(0);

  Use this method only for primitive elements. If the element is a PropertySet, use GetElementAsPropertySetAt() instead.

• GetElementAsPropertySetAt(index):Returns the PropertySet element at the specified zero-based position.

  var child = ps.GetElementAsPropertySetAt(3);

  Use this method only when the element at that position is a PropertySet. A common pattern is to call IsElementPropertySetAt(index) first.