//
// SPDX-License-Identifier: BSD-3-Clause
// Copyright Contributors to the OpenEXR Project.
//

-----------
Terminology
-----------

Items - Similar to 'list items'.  Can think of as the 'vertical'
        dimension similar to the other FixedArray dimension.  Each item
        contains an array of varying length.

Elements - The 'variable-length' array members of each item.  In this
           case, each 'element' is an int.  For a FloatVArray, the 
           elements would be floats.


------------
Construction
------------

v = IntVArray()
    : Do not support; FixedArrays generally don't have empty construction.

v = IntVArray(10)
    : Creates 10 items, each item has zero elements (i.e. empty).

v = IntVArray(int initialValue , 10, 5)
    : Creates 10 items, each item has 5 elements that are initialized
      to the initialValue.

v = IntVArray(IntArray initialValue, 10)
    : Creates 10 items, each initialized with a copy of the elements of
      the provided initialValue IntArray.

v = IntVArray([1, 2, 3], 10)
    : Creates 10 items, each initialized with the elements of the provided
      list.  This would be similar to the previous constructor, but with
      a different initialValue type.  We probably don't want to support
      this right away, but possibly at some point in the future.

v = IntVArray(int intialValue, IntArray() initialLengths)
    : Creates initialLengths.len() items each with a number of elements
      matching the values provided by the initialLengths array.  The
      initial value for all elements is 'initalValue'.

v = IntVArray(IntVArray clone)
    : Created as a copy of 'clone'.


Usage (Accessing)
-----------------

int = v.len()  (number of items)

IntArray  = v[4]   (reference of v's data)
IntArray  = v[-1]  (same as previous)
IntVArray = v[3:9] (reference of v's data; stride provides indexing)
IntVArray = v[:]   (same as previous, stride probably not needed)

IntVArray = v[IntArray mask]
    : Returns a reference of v's data; uses mask variable internally
IntVArray = v[BoolArray mask]
    : Not currently supported, but would provide the same as previous.
      This 'BoolArray' mask should be implemented sometime soon (for
      this and all other FixedArrays).

<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
Question: Support v[5][2] semantics.  This might work out-of-the-box since
          v[5] would return an IntArray, which supports [] also.  In this
          case it would be fine and a single 'int' would be returned.
          But for v[5][1:3], we would return another IntArray
          instead of a regular int, so the levels of indirection 
          for original internal IntVArray data might get too complicated.  Do
          we support this semantic or not.  The problem is that if we don't
          want to support it, we'll have to specifically disable it somehow
          since we'll get it by default (v[5] returns IntArray, which would
          automatically support [1:3]).

Question: To avoid the previous issue, we'll probably want a special element
          accessor method (probably called 'element').  That'll have to have
          the ability to take in a 'slice' as an argument.  Would that all
          work?

In the continuing text, we'll assume we support an 'element' accessor
method and not the [5][6] double-box notation.
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

int      = v[4].element(1)        (returns a single integer)
int      = v[4].element(-1)       (same as previous)
IntArray = v[4].element(2:7)      (return IntArray referencing original data)
IntArray = v[4].element(:)        (same as previous; no 'stride' needed)
int      = v[4].len()             (would not work; int doesn't support 'len')
int      = v[4].element(:).len()  (the number of elements for item 4 ???)

IntArray  = v[3:9].element(1)  (All of the element-1 members for items 3 - 9)
IntArray  = v.element(1)       (All of the element-1 members for each item)
IntArray  = v[3:9].element(-1) (same as previous, but returns last elements)
IntVArray = v[3:9].element(2:7)  (subset of the original ?????)
IntVArray = v[3:9].element(:)  (subset of the original v; only items 3 - 9)
int 6     = v[3:9].len()

IntArray  = v[:].element(1)   (List of all element-1s from all items ???)
IntArray  = v[:].element(-1)  (List of all last elements ???)
IntVArray = v[:].element(2:7) (subset of the original ????)
IntVArray = v[:].element(:)   (basically a reference of the original)
int       = v[:].len()        (number of items in v)

<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
Question: We want to support easy indexing right into a 'X' V3fArray 
          or something similar.  Lets say we want to add a V3f to all
          coordinates of the entire system.  We'd want to be able to
          write expressions like:

              x[ v[:].element(:) ] += imath.V3f(1,2,3)
              x[ v[:].element(0) ] += imath.V3f(1,2,3)  (the 'root' point)
              x[ v[3].element(:) ] += ...
              x[ v[1:10].element(:) ] += ...
              x[ v[1:10].element(1:4) ] += ...

          But in many cases, the expression returns another IntVArray.
          Should/can we provide indexing into V3fArray from an IntVArray?
          Do we currently support indexing into a V3fArray from IntArray?
          What other ways can we make this convenient.
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
Question: What about cases where not all items support the same number
          of elements.  What happens in these cases:

              IntArray = v[:].element(7)

          for cases where some or all of the items don't have an element-7.
          Would the IntArray be a subset of v's items (i.e. if only 3 items
          could return an element-7, the IntArray would be 3 long).  Or
          would the IntArray contain invalid/None/undefined integers within
          it.
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
Question: What other accessor/modification methods do we want to support.
          append, remove, pop, push, etc?
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

