Skip to main content

3. Additional Array Tags

3. Additional Array Tags​

This specification defines three additional array tags. The Multi-dimensional Array tags can be combined with classical CBOR arrays as well as with Typed Arrays in order to build multi-dimensional arrays with constant numbers of elements in the sub-arrays. The Homogeneous Array tag can be used as a signal by an application to identify a classical CBOR array as a homogeneous array, even when a Typed Array does not apply.

3.1 Multi-dimensional Array​

A multi-dimensional array is represented as a tagged array that contains two (one-dimensional) arrays. The first array defines the dimensions of the multi-dimensional array (in the sequence of outer dimensions towards inner dimensions) while the second array represents the contents of the multi-dimensional array. If the second array is itself tagged as a Typed Array, then the element type of the multi-dimensional array is known to be the same type as that of the Typed Array.

Two tags are defined by this document: one for elements arranged in row-major order and another for column-major order [RowColMajor].

3.1.1 Row-Major Order​

Tag: 40

Data Item: Array (major type 4) of two arrays: one array (major type 4) of dimensions, which are unsigned integers distinct from zero; and one array (any one of a CBOR array of major type 4, a Typed Array, or a Homogeneous Array) of elements.

Data in the second array consists of consecutive values where the last dimension is considered contiguous (row-major order).

Figure 1 shows a declaration of a two-dimensional array in the C language, a representation of that in CBOR using both a multi-dimensional array tag and a typed array tag.

uint16_t a[2][3] = {
  {2, 4, 8},   /* row 0 */
  {4, 16, 256},
};

<Tag 40> # multi-dimensional array tag
   82       # array(2)
     82      # array(2)
       02     # unsigned(2) 1st Dimension
       03     # unsigned(3) 2nd Dimension
     <Tag 65> # uint16 array
       4c     # byte string(12)
         0002 # unsigned(2)
         0004 # unsigned(4)
         0008 # unsigned(8)
         0004 # unsigned(4)
         0010 # unsigned(16)
         0100 # unsigned(256)

           Figure 1: Multi-dimensional Array in C and CBOR

Figure 2 shows the same two-dimensional array using the multi-dimensional array tag in conjunction with a basic CBOR array (which, with the small numbers chosen for the example, happens to be shorter).

<Tag 40> # multi-dimensional array tag
   82       # array(2)
     82      # array(2)
       02     # unsigned(2) 1st Dimension
       03     # unsigned(3) 2nd Dimension
     86     # array(6)
       02      # unsigned(2)
       04      # unsigned(4)
       08      # unsigned(8)
       04      # unsigned(4)
       10      # unsigned(16)
       19 0100 # unsigned(256)

       Figure 2: Multi-dimensional Array Using Basic CBOR Array

3.1.2 Column-Major Order​

The multi-dimensional arrays specified in the previous sub-subsection are in "row major" order, which is the preferred order for the purposes of this specification. An analogous representation that uses "column major" order arrays is provided in this subsection under the tag 1040, as illustrated in Figure 3.

Tag: 1040

Data Item: The same as tag 40, except the data in the second array consists of consecutive values where the first dimension is considered contiguous (column-major order).

<Tag 1040> # multi-dimensional array tag, column-major order
   82       # array(2)
     82      # array(2)
       02     # unsigned(2) 1st Dimension
       03     # unsigned(3) 2nd Dimension
     86     # array(6)
       02      # unsigned(2)
       04      # unsigned(4)
       04      # unsigned(4)
       10      # unsigned(16)
       08      # unsigned(8)
       19 0100 # unsigned(256)

  Figure 3: Multi-dimensional Array Using Basic CBOR Array, Column-
                             Major Order

3.2 Homogeneous Array​

Tag: 41

Data Item: Array (major type 4)

This tag identifies the classical CBOR array (a one-dimensional array) tagged by it as a homogeneous array, that is, it has elements that are all of the same application model data type. The element type of the array is therefore determined by the application model data type of the first array element.

This can be used in application data models that apply specific semantics to homogeneous arrays. Also, in certain cases, implementations in strongly typed languages may be able to create native homogeneous arrays of specific types instead of ordered lists while decoding. Which CBOR data items constitute elements of the same application type is specific to the application.

Figure 4 shows an example for a homogeneous array of booleans in C++ [CPlusPlus] and CBOR.

bool boolArray[2] = { true, false };

<Tag 41>  # Homogeneous Array Tag
   82           #array(2)
      F5        # true
      F4        # false

             Figure 4: Homogeneous Array in C++ and CBOR

Figure 5 extends the example with a more complex structure.

typedef struct {
  bool active;
  int value;
} foo;
foo myArray[2] = { {true, 3}, {true, -4} };

<Tag 41>
    82  # array(2)
       82  #  array(2)
             F5  # true
             03  # 3
       82 # array(2)
             F5  # true
             23  # -4

             Figure 5: Homogeneous Array in C++ and CBOR
Last updated on