;================================================================
; common/common_utils 通用工具函数
; utils_array.erb 数组操作
;
;     1. 均为行内函数形式是考虑到兼容性
;        毕竟一般函数中可以调用行内函数, 行内函数中不能调用一般行数
;
;     2. 不兼容本来就包含 0 或 ""(空字符串) 的数组
;        因为无法区分到底是 默认的初始值 还是真的就是 0 或 ""
;================================================================


;;;整型数组向末尾添加一个元素
;;;- (ref)int array 数组变量
;;;- int input 新的尾部元素
;;;@return 新的数组长度
@int_array_push(array, input)
#FUNCTION
    #DIM REF array
    #DIM input
    #DIM DYNAMIC i
    FOR i, 0, VARSIZE("array")
        IF array:i == 0
            array:i = input
            RETURNF i + 1
        ENDIF
    NEXT
    RETURNF -1


;;;整型数组移除最后一个元素
;;;- (ref)int array 数组变量
;;;@return 移除的元素
@int_array_pop(array)
#FUNCTION
    #DIM REF array
    #DIM DYNAMIC i
    #DIM DYNAMIC output
    output = -1
    FOR i, 0, VARSIZE("array")
        IF array:i == 0
            output = array:(i - 1)
            array:(i - 1) = 0
            BREAK
        ENDIF
    NEXT
    RETURNF output


;;;整型数组向开头添加一个元素
;;;- (ref)int array 数组变量
;;;- int input 新的头部元素
;;;@return 新的数组长度
@int_array_shift(array, input)
#FUNCTION
    #DIM REF array
    #DIM input
    #DIM DYNAMIC i
    ARRAYSHIFT array, 1, 0
    array:0 = input
    FOR i, 0, VARSIZE("array")
        SIF array:i == 0
            RETURNF i
    NEXT
    RETURNF -1


;;;整型数组移除第一个元素
;;;- (ref)int array 数组变量
;;;@return 移除的元素
@int_array_unshift(array)
#FUNCTION
    #DIM REF array
    #DIM DYNAMIC output
    output = array:0
    ARRAYSHIFT array, -1, 0
    RETURNF output


;;;获取整型数组的长度
;;;- (ref)int array 数组变量
;;;@return 数组长度
@int_array_len(array)
#FUNCTION
    #DIM REF array
    #DIM DYNAMIC array_max_length
    #DIM DYNAMIC i
    array_max_length = VARSIZE("array")
    FOR i, 0, array_max_length
        SIF array:i == 0
            RETURNF i
    NEXT
    RETURNF array_max_length


;;;字符串数组向末尾添加一个元素
;;;- (ref)str array 数组变量
;;;- str input 新的尾部元素
;;;@return 新的数组长度
@str_array_push(array, input)
#FUNCTION
    #DIMS REF array
    #DIMS input
    #DIM DYNAMIC i
    FOR i, 0, VARSIZE("array")
        IF array:i == ""
            array:i '= input
            RETURNF i + 1
        ENDIF
    NEXT
    RETURNF -1


;;;字符串数组移除最后一个元素
;;;- (ref)str array 数组变量
;;;@return 移除的元素
@str_array_pop(array)
#FUNCTIONS
    #DIMS REF array
    #DIM DYNAMIC i
    #DIMS DYNAMIC output
    FOR i, 0, VARSIZE("array")
        IF array:i == ""
            output '= array:(i - 1)
            array:(i - 1) '= ""
            BREAK
        ENDIF
    NEXT
    RETURNF output


;;;字符串数组向开头添加一个元素
;;;- (ref)str array 数组变量
;;;- str input 新的头部元素
;;;@return 新的数组长度
@str_array_shift(array, input)
#FUNCTION
    #DIMS REF array
    #DIMS input
    #DIM DYNAMIC i
    #DIM DYNAMIC end_index
    FOR i, 0, VARSIZE("array")
        IF array:i == ""
            end_index = i
            BREAK
        ENDIF
    NEXT
    FOR i, end_index, 0, -1
        array:i '= array:(i - 1)
    NEXT
    array:0 '= input
    RETURNF end_index + 1


;;;字符串数组移除第一个元素
;;;- (ref)str array 数组变量
;;;@return 移除的元素
@str_array_unshift(array)
#FUNCTIONS
    #DIMS REF array
    #DIM DYNAMIC i
    #DIM DYNAMIC length_max_limit
    #DIMS DYNAMIC output
    output '= array:0
    length_max_limit = VARSIZE("array")
    FOR i, 0, length_max_limit
        SIF array:i == ""
            BREAK
        SIF i + 1 < length_max_limit
            array:i '= array:(i + 1)
    NEXT
    RETURNF output


;;;字符串数组的长度
;;;- (ref)str array 数组变量
;;;@return 数组长度
@str_array_len(array)
#FUNCTION
    #DIMS REF array
    #DIM DYNAMIC array_max_length
    #DIM DYNAMIC i
    array_max_length = VARSIZE("array")
    FOR i, 0, array_max_length
        SIF array:i == ""
            RETURNF i
    NEXT
    RETURNF array_max_length
