3D array datastructure functions

// This source code is subject to the terms of the Mozilla Public License 2.0 at https://mozilla.org/MPL/2.0/
// © Joris Duyck

//@version=4
study("3D_array_datastructure functions")

// 3D MATRIX FUNCTIONS, the matrix is set up as an excell workbook
// and is devided in sheets, rows/records and columns
//
//
// the matrix has the following structure:
// 
// the array starts with 3 values describing the dimension information,
// followed by the actual data
//
//
/////////////////////////////////////////////////////////////////////////////// 
//         (header with dimensions info)
//
// [nr_of_sheets, nr_of_rows/records, nr_of_columns,
//
//           (actual array data)
// 
//          SHEET 0
//  
//            0           1           2           3                   column_index
//  0    record0_val0, record0_val1, record0_val2, record0_val3, ...,
//  1    record1_val1, record1_val1, record1_val2, record1_val3, ...,
//  2    record2_val0, record2_val1, record2_val2, record2_val3, ...,
//  3    ...
//
// row_index
//
//                   SHEET 1
//           
//                      0           1           2           3                   column_index
//           0    record0_val0, record0_val1, record0_val2, record0_val3, ...,
//           1    record1_val0, record1_val1, record1_val2, record1_val3, ...,
//           2    record2_val0, record2_val1, record2_val2, record2_val3, ...,
//           3    ...
//          
//          row_index
//
//                                SHEET 2
//                        
//                                   0           1           2           3                   column_index
//                        0    record0_val0, record0_val1, record0_val2, record0_val3, ...,
//                        1    record1_val0, record1_val1, record1_val2, record1_val3, ...,
//                        2    record2_val0, record2_val1, record2_val2, record2_val3, ...,
//                        3    ...                                                          ]
//                       
//                       row_index
//

// 3D matrix initialisation function, builds 3D matrix with dimensional metadata/size in first 3 values //
// syntax = "f_3D_array_new(nr of sheets, nr of records, nr of columns)"
f_3D_array_new(_nr_of_sheets, _nr_of_rows, _nr_of_columns, _fill) =>
    _size  = int(_nr_of_sheets * _nr_of_rows * _nr_of_columns)
    _m     = array.new_float(3 + _size, _fill)
    array.set(_m, 0, _nr_of_sheets), array.set(_m, 1, _nr_of_rows), array.set(_m, 2, _nr_of_columns)
    _m

// function to get dimensional info from 3D matrix
f_3D_array_get_size(_m) =>
    _nr_of_sheets  = int(array.get(_m, 0))
    _nr_of_rows    = int(array.get(_m, 1))
    _nr_of_columns = int(array.get(_m, 2))
    [_nr_of_sheets, _nr_of_rows, _nr_of_columns]

// function to get a sheet start and end index from 3D matrix
f_3D_array_get_sheet_index_range(_m, _sheet_index) =>
    [_nr_of_sheets, _nr_of_rows, _nr_of_columns] = f_3D_array_get_size(_m)
    _start_index = 3 + min(_sheet_index, (_nr_of_sheets - 1)) * _nr_of_rows * _nr_of_columns
    _end_index   = _start_index + _nr_of_rows * _nr_of_columns - 1
    [_start_index, _end_index]

// function to add a record on the top of a sheet and remove the oldest record ("sheet_index" goes from 0 (first) to 1, 2, ...)//
f_3D_array_add_new_record(_m, _sheet_index, _record) =>
    [_nr_of_sheets, _nr_of_rows, _nr_of_columns] = f_3D_array_get_size(_m)
    if array.size(_record) == 3
        [_sheet_start_index, _sheet_end_index] = f_3D_array_get_sheet_index_range(_m, _sheet_index)
        _sheet = array.slice(_m, _sheet_start_index, _sheet_end_index + 1)
        for i = (3 - 1) to 0
            array.unshift(_sheet, array.get(_record, i))
            array.pop(_sheet)
    _m

// function to retrieve the values from a record from a certain row/lookback period ("sheet_index" goes from 0 (first) to 1, 2, ..., "row_index" goes from 0 (latest) to 1, 2, ...(oldest) )//
f_3D_array_get_record(_m, _sheet_index, _row_index) =>
    [_nr_of_sheets, _nr_of_rows, _nr_of_columns] = f_3D_array_get_size(_m)
    [_sheet_start_index, _sheet_end_index] = f_3D_array_get_sheet_index_range(_m, min(_nr_of_sheets - 1, _sheet_index))
    _start_index = _sheet_start_index + min(_nr_of_rows - 1, _row_index) * _nr_of_columns 
    _sheet = array.slice(_m, _start_index, _start_index + min(_sheet_end_index + 1, _nr_of_columns))
    _record = array.copy(_sheet)
    _record


// function to print matrix (needs some adjustment )
//{
f_array_print(_m, _nr_of_dimensions, _header) =>
    _text = _nr_of_dimensions <= 1 or not _header ? "" : "(" + tostring(array.get(_m, 0)) + "x" + tostring(array.get(_m, 1)) + (_nr_of_dimensions <= 2 ? "" : "x" + tostring(array.get(_m, 2))) + ")" + "\n" + "\n"
    _text := _text + "[" + (_nr_of_dimensions == 1 or not _header ? tostring(array.get(_m, 0)) + " "  : "")
    
    for i = _nr_of_dimensions to array.size(_m) - 1
        _text := _text + (i == _nr_of_dimensions ? "" : ((i - _nr_of_dimensions) % array.get(_m, 2)) == 0 ? "]" + "\n" + (i >= array.get(_m, 1) * array.get(_m, 2) + 2 ? "            " : "") + "[" : " ") + tostring(array.get(_m, i))
    _text := _text + "]"
//}

/// test section ///
// set test matrices
//{
a = f_3D_array_new(2, 3, 3, 0) 

array.set(a, 3, 0),   array.set(a, 4, 1),  array.set(a, 5, 2)
array.set(a, 6, 3),   array.set(a, 7, 4),  array.set(a, 8, 5)
array.set(a, 9, 6),   array.set(a, 10, 7), array.set(a, 11, 8)

array.set(a, 12, 9),  array.set(a, 13, 10), array.set(a, 14, 11)
array.set(a, 15, 12), array.set(a, 16, 13), array.set(a, 17, 14)
array.set(a, 18, 15), array.set(a, 19, 16), array.set(a, 20, 17)


b = array.copy(a)


new_record = array.new_float(3, 0)
array.set(new_record, 0, 10)
array.set(new_record, 1, 20)
array.set(new_record, 2, 30)
//}


// parameters to check behavior of functions
//{
x = input(1, title="record insert sheet index")
y = input(0, title="record get sheet index")
z = input(1, title="record get row index")
//}

c = f_3D_array_add_new_record(a, 1, new_record) 
// c := f_3D_array_add_new_record(a, x, new_record) 
e = f_3D_array_get_record(a, y, z)

// plot matrices
//{
// copy of original matrix before "manipulation"
var label lbl_b = na, label.delete(lbl_b)
lbl_b := label.new(bar_index - 30, 0, text = f_array_print(b, 3, true), textalign = text.align_left)

// new record array
var label lbl_new_record = na, label.delete(lbl_new_record)
lbl_new_record := label.new(bar_index - 20, 0, text = f_array_print(new_record, 1, false), textalign = text.align_left)

// resulting matrix
var label lbl_c = na, label.delete(lbl_c)
lbl_c := label.new(bar_index - 10, 0, text = f_array_print(c, 3, true), textalign = text.align_left)

// extracted record
var label lbl_e = na, label.delete(lbl_e)
lbl_e := label.new(bar_index - 0, 0, text = f_array_print(e, 1, false), textalign = text.align_left)
//}