---------------------------------------------------------- Variable-length Fixed Array 'IntVArray' - Python Interface ---------------------------------------------------------- ----------- 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? <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>