Repeating Elements

---

Elements within a sequence definition may be declared to be repeating by using the minOccurs and/or maxOccurs facets. In this case, a C or C++ list or array container type structure is used instead of a C/C++ element type definition. This container holds a series of objects of the element type.

If the C element type is a simple type and the maximum number of elements (maxOccurs) is less than or equal to 10,000, then an array type of the following form is used:

struct {

OSUINT32 n;

ElemType elem[maxOccurs];

}

In this definition, n is used to hold the count of element occurrences to be encoded (or that were decoded), and data holds the actual element data values.

If either of the above conditions is not true, a linked list type is used to hold a dynamic list of the data objects. This type is OSRTDList (run-time doubly linked list). It is defined in rtxDList.h as follows:

/* Doubly-linked list types */

typedef struct _OSRTDListNode {

const void* data;

struct _OSRTDListNode* next;

struct _OSRTDListNode* prev;

} OSRTDListNode;

typedef struct _OSRTDList {

OSUINT32 count;

OSRTDListNode* head;

OSRTDListNode* tail;

} OSRTDList;

There is a complete set of functions available for adding, deleting, and traversing lists of this type available in the run-time library. See the Doubly-Linked List Utility Functions section for documentation on these functions.

For C++, there are corresponding class definitions (OSRTDListClass and OSRTObjListClass) that extend the OSRTDList structure and contain constructors and methods for adding, removing, and finding items in the list.

The following example shows a sequence with two repeating elements. The first will cause an array type to be generated, the second, a list:

<xsd:complexType name="SeqWithArrayAndList">

<xsd:sequence>

<xsd:element name="anArray" type="xsd:integer"

maxOccurs="10"/>

<xsd:element name="aList" type="SomeOtherType"

maxOccurs="unbounded"/>

</xsd:sequence>

</xsd:complexType>

The C type that is generated for this XSD type is as follows:

typedef struct SeqWithArrayAndList {

struct {

OSUINT32 n;

OSINT32 elem[10];

} anArray;

/* List of SomeOtherType */

OSRTDList aList;

} SeqWithOptElem;

Note that a comment is added to the generated C structure before the list declaration to indicate what type of objects the list is to contain.

In the case of C++, a constructor is added to the generated array structure to initialize the number of elements to zero. An inline class is generated for the list variable that extends the OSRTDListClass or OSRTObjListClass and adds methods to append items to the list and retrieve items from the list:

class SeqWithArrayAndList : public OSBaseType {
 
public:
 
   struct anArray_array {
 
      OSUINT32 n;
 
      OSINT32 elem[10];
 
      anArray_array() { n = 0; }
 
   } anArray;
 
   /* List of SomeOtherType */
 
   class aList_list : public OSRTDListClass {
 
    public:
 
      void append (const SomeOtherType* pdata) {
 
         OSRTDListClass::append ((const void*)pdata);
 
      }
 
      void append (SomeOtherType* pdata, OSBOOL ownMemory=FALSE) {
 
         OSRTDListClass::append ((void*)pdata, ownMemory);
 
      }
 
      const SomeOtherType* getItem (int idx) {
 
         return (const SomeOtherType*) OSRTDListClass::getItem (idx);
 
      }
 
   } aList;
 
   ...
 
} ;
 

The ownMemory argument on the second append method is used to transfer memory ownership of the object over to the list. If this is set to true, the object will be deleted at the time the list object is deleted or goes out of scope. Otherwise, the object will persist and the user will be responsible for deleting it at some later time.