Serviço ScriptForge.Array (SF_Array)

Sumário

# Serviço ScriptForge.Array

Fornece uma coleção de métodos para manipular e transformar Arrays de uma dimensão (vetores) e Arrays de duas dimensões (matrizes). Isso inclui operações de conjuntos, ordenação, bem como importação e exportação de arquivos texto.

Arrays com mais de duas dimensões não podem ser usados em métodos deste serviço, com a única exceção do método CountDims que aceita arrays com qualquer número de dimensões.

Itens do vetor podem conter valores de qualquer tipo, incluindo subvetores.

Matrizes unidimensionais contendo apenas submatrizes unidimensionais são chamadas abaixo de matrizes de dados. Eles são particularmente adequados para trocas de dados tabulares com scripts Python e planilhas Calc.

## Invocação do serviço

Antes de usar o serviço Array a biblioteca ScriptForge precisa ser carregada usando:

        GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

Carregar a biblioteca criará o objeto SF_Array que pode ser usado para chamar os métodos do serviço Array.

Os trechos de código a seguir mostram as várias maneiras de chamar os métodos do serviço Array (o método Append é usado como um exemplo):

        Dim arr : arr = Array(1, 2, 3)
        arr = SF_Array.Append(arr, 4)

        Dim arr : arr = Array(1, 2, 3)
        Dim svc : svc = SF_Array
        arr = svc.Append(arr, 4)

        Dim arr : arr = Array(1, 2, 3)
        Dim svc : svc = CreateScriptService("Array")
        arr = svc.Append(arr, 4)

Como a linguagem Python possui suporte integrado a listas e tuplas, a maioria dos métodos no serviço Array estão disponíveis apenas para macros em Basic. A única exceção é o método ImportFromCSVFile que é suportado tanto em Basic como em Python.

Lista de Métodos no Serviço Array
Append AppendColumn AppendRow Contains ConvertFromDataArray ConvertToDataArray ConvertToDictionary ConvertToRange Copy CountDims Difference ExportToTextFile | ExtractColumn ExtractRow Flatten ImportFromCSVFile IndexOf Insert InsertSorted Intersection Join2D Prepend PrependColumn PrependRow | RangeInit Reverse Shuffle Slice Sort SortColumns SortRows Transpose TrimArray Union Unique

O primeiro argumento da maioria dos métodos é o objeto Array a ser considerado. Ele é sempre passado por referência e não é alterado. Métodos como Append, Prepend, etc retornam um novo objeto Array após sua execução.

## Append

Concatena os itens listados como argumentos ao final do array de entrada.

### Sintaxe:

svc.Append(array_1d: any[0..*], arg0: any, [arg1: any] ...): any[0..*]

### Parâmetros:

array_1d: o array pré-existente, pode ser vazio.

arg0, arg1, ...: itens que serão acrescentados ao array_1d.

### Exemplo:

        Dim a As Variant
        a = SF_Array.Append(Array(1, 2, 3), 4, 5)
            ' (1, 2, 3, 4, 5)

## AppendColumn

Concatena uma nova coluna à direita de um array de duas dimensões. O array resultante tem os mesmos limitantes inferiores que o array de duas dimensões original.

### Sintaxe:

svc.AppendColumn(array_2d: any[0..*, 0..*], column: any[0..*]): any[0..*, 0..*]

### Parâmetros:

array_2d: array pré existente, pode ser vazio. Se o array contém apenas uma dimensão, então ele é considerado como a primeira coluna da matriz de duas dimensões resultante.

column: um array de uma dimensão com a mesma quantidade de itens que a quantidade de linhas em array_2d.

### Exemplo:

        Dim a As Variant, b As variant
        a = SF_Array.AppendColumn(Array(1, 2, 3), Array(4, 5, 6))
            ' ((1, 4), (2, 5), (3, 6))
        b = SF_Array.AppendColumn(a, Array(7, 8, 9))
            ' ((1, 4, 7), (2, 5, 8), (3, 6, 9))
        c = SF_Array.AppendColumn(Array(), Array(1, 2, 3))
            ' ∀ i ∈ {0 ≤ i ≤ 2} : b(0, i) ≡ i

## AppendRow

Concatena uma nova linha à parte de baixo de um array de duas dimensões. O array resultante tem os mesmos limitantes inferiores que o array de duas dimensões original.

### Sintaxe:

svc.AppendRow(array_2d: any[0..*, 0..*], row: any[0..*]): any[0..*, 0..*])

### Parâmetros:

array_2d: array pré-existente, pode ser vazio. Se o array tiver uma dimensão, ele é considerado como a primeira linha do array de duas dimensões resultante.

row: um array de uma dimensão com a mesma quantidade de itens que a quantidade de colunas em array_2d.

### Exemplo:

        Dim a As Variant, b As variant
        a = SF_Array.AppendRow(Array(1, 2, 3), Array(4, 5, 6))
            '  ((1, 2, 3), (4, 5, 6))
        b = SF_Array..AppendRow(Array(), Array(1, 2, 3))
            ' ∀ i ∈ {0 ≤ i ≤ 2} : b(i, 0) ≡ i

## Contains

Verifica se um array de uma dimensão contém um certo número, texto ou data. Comparação de texto pode ser sensível ao caso ou não.
Arrays de entrada ordenados devem ser preenchidos homogeneamente, ou seja, todos os itens deve ser escalares de um mesmo tipo. (Itens Empty e Null não são permitidos).
O resultado do método é imprevisível quando o array é anunciado como ordenado e de fato não é.
Uma busca binária é feita quando o array é ordenado, caso contrário ele é simplesmente escaneado de cima para baixo e valores Empty e Null são ignorados.

### Sintaxe:

svc.Contains(array_1d: any[0..*], tofind: any, casesensitive: bool = False, sortorder: str = ""): bool

### Parâmetros:

array_1d: O array para ser usado na busca.

tofind: um número, data ou texto a ser procurado.

casesensitive: Apenas para comparação de strings. (Padrão = False).

sortorder: pode ser "ASC" (crescente), "DESC" (decrescente) ou "" (não ordenado). O valor padrão é "".

### Exemplo:

        Dim a As Variant
        a = SF_Array.Contains(Array("A","B","c","D"), "C", SortOrder := "ASC") ' True
        SF_Array.Contains(Array("A","B","c","D"), "C", CaseSensitive := True) ' False

## ConvertFromDataArray

Converta um array de dados em um array Básico.
Um array de dados é um array de submatrizes. Mediante solicitação, os itens de saída individuais são reduzidos apenas a strings ou duplos.

O método retorna um escalar, um array 1D com base em zero ou um array 2D com base em zero.
O número de colunas no array 2D resultante é igual ao número de itens no primeiro subarray. Se os próximos subarrays tiverem um tamanho diferente, as próximas linhas serão complementadas com o argumento fillvalue ou truncadas.

### Sintaxe:

svc.ConvertFromDataArray(dataarray: any[any[0..*], ...], isrange: bool = False, fillvalue: str = ''): any[0..*, 0..*]

### Parâmetros:

dataarray: uma matriz de submatrizes. Matrizes e submatrizes devem ser baseadas em zero.
Normalmente, uma matriz de dados é gerada por

- o método session.ExecuteCalcFunction()

- Um script Python que retorna uma tupla de tuplas

- o get DataArray() método de com.sun.star.sheet.XCellRange Data interface

isrange: Quando True (padrão = False), os itens são convertidos em strings ou números de ponto flutuante de dupla precisão.

fillvalue: Como substituir itens ausentes. O padrão é uma string vazia.

### Exemplo:

        Dim dataarray As Variant, array2D As Variant
        dataarray = Array(Array("Col1", "Col2", "Col3"), Array(10, 20, 30))
        array2D = SF_Array.ConvertFromDataArray(dataarray)
        MsgBox array2D(1, 2) ' 30

## ConvertToDataArray

Crie uma matriz de dados a partir de um escalar, uma matriz unidimensional ou uma matriz bidimensional.
Uma matriz de dados é uma matriz de submatrizes com base zero. Sob demanda, os itens de saída individuais são reduzidos a strings ou números de ponto flutuante de dupla precisão.

A matriz de dados retornada é normalmente usada como

- uma tupla de (sub)tuplas passada para um script Python

- argumento do método setDataArray() da interface com.sun.star.sheet.XCellRangeData

### Sintaxe:

svc.ConvertToDataArray(data: any[0..*, 0..*], isrange: bool = False, rows: int = 0, columns: int = 0): any[any[0..*], ...]

### Parâmetros:

dados: O valor escalar de entrada, matriz 1D ou 2D.

isrange: Quando True (padrão = False), os itens da matriz são armazenados como strings (possivelmente vazias) ou números de ponto flutuante de dupla precisão na matriz de dados.

linhas, colunas: O número de linhas ou colunas da matriz de dados retornada. Quando excederem os limites de dados, preencha com strings de comprimento zero. Se linhas = 1 e a matriz de entrada for um vetor, a matriz de dados será alinhada horizontalmente (por padrão, vetores são alinhados verticalmente). Quando ausente, o tamanho da saída será determinado pela matriz de entrada.

### Exemplo:

        Dim data As Variant, dataarray As Variant
        data = Array(1, 2, 3)
        data = SF_Array.AppendRow(data, Array(4, 5, 6))
        dataarray = SF_Array.ConvertToDataArray(data)
        MsgBox dataarray(1)(2) ' 6

## ConvertToDictionary

Armazena o conteúdo de um array de 2 colunas em um objeto ScriptForge.Dictionary.
A chave é extraída da primeira coluna e o item é extraído da segunda coluna.

### Sintaxe:

svc.ConvertToDictionary(array_2d: any[0..*, 0..1]): obj

### Parâmetros:

array_2d: dados a serem convertidos em um objeto ScriptForge.Dictionary.

- A primeira coluna deve conter exclusivamente strings com comprimento maior que zero, em qualquer ordem. Estes valores serão usados como rótulos no dicionário.

- A segunda coluna contém os dados que serão associados aos rótulos correspondentes no dicionário.

### Exemplo:

        Dim a As Variant, b As Variant
        a = SF_Array.AppendColumn(Array("a", "b", "c"), Array(1, 2, 3))
        b = SF_Array.ConvertToDictionary(a)
        MsgBox b.Item("c") ' 3

## ConvertToRange

Crie um intervalo de células válido a partir de um escalar, uma matriz unidimensional, uma matriz bidimensional ou uma matriz de dados (uma matriz de dados é uma matriz de submatrizes com base zero). Os limites inferiores das matrizes são preservados na saída.

Os itens individuais são sempre reduzidos a strings ou números de ponto flutuante de dupla precisão, incluindo valores booleanos ou datas.

O escalar ou array 2D retornado é um argumento válido do método session.ExecuteCalcFunction(). Isso é particularmente útil no contexto de funções de array [complexas].

### Sintaxe:

svc.ConvertToRange(data: any[0..*, 0..*], direction: str = 'V' | 'H'): any[0..*, 0..*]

### Parâmetros:

dados: O escalar de entrada, matriz 1D, matriz 2D ou matriz de dados.

direction: O alinhamento do intervalo quando se trata de um vetor, podendo ser "V" [vertical, padrão] ou "H" [orizontal].

### Exemplo:

        Dim session As Variant  :  session = CreateScriptService"Session")
        Dim matrix As Variant, result As Variant
        matrix = Array(-1, 2, 3)
        matrix = SF_Array.AppendRow(matrix, Array(4, -5, 6))
        matriz = SF_Array.AppendRow(matriz, Array(7, 8, -9))
        result = session.ExecuteCalcFunction("ABS", SF_Array.ConvertToRange(matrix))
        MsgBox result(2)(2) ' 9 - result is a data array

## Copy

Cria uma cópia de um array de uma ou duas dimensões.

### Sintaxe:

svc.Copy(array_nd: any[0..*]): any[0..*]

svc.Copy(array_nd: any[0..*, 0..*]): any[0..*, 0..*]

### Parâmetros:

array_nd: array a ser copiado, com uma ou duas dimensões.

### Exemplo:

Uma atribuição simples de um objeto Array copiará sua referência em vez de criar uma cópia dos conteúdos do objeto. Veja o exemplo abaixo:

        Dim a as Variant, b as Variant
        a = Array(1, 2, 3)
        ' A atribuição abaixo é feita por referência
        b = a
        ' Logo, mudar valores em "b" também mudará "a"
        b(0) = 10
        MsgBox a(0) ' 10

Ao usar o método Copy, uma cópia de todo o objeto Array é feita. No exemplo abaixo, a e b são objetos diferentes e mudar os valores em b não afeta os valores em a.

        Dim a as Variant, b as Variant
        a = Array(1, 2, 3)
        ' Cria uma cópia de "a" usando o método "Copy"
        b = SF_Array.Copy(a)
        b(0) = 10
        MsgBox a(0) ' 1

## CountDims

Conta o número de dimensões de um array. O resultado pode ser maior que 2.
Se o argumento não é um array, retorna -1
Se o array não está inicializado, retorna 0.

### Sintaxe:

svc.CountDims(array_nd: any): int

### Parâmetros:

array_nd: array a ser examinado.

### Exemplo:

        Dim a(1 To 10, -3 To 12, 5)
        MsgBox SF_Array.CountDims(a) ' 3

## Difference

Constrói um conjunto, como um array indexado em zero, aplicando o operador "diferença" aos dois arrays de entrada. Os itens resultantes se originam do primeiro array e não do segundo.
O array resultante é ordenado de maneira ascendente.
Ambos arrays de entrada devem ser preenchido homogeneamente, seus itens devem ser escalares do mesmo tipo. Itens Empty e Null não são permitidos.
Comparação de texto pode ser sensível ao caso ou não.

### Sintaxe:

svc.Difference(array1_1d: any[0..*], array2_1d: any[0..*], casesensitive: bool = False): any[0..*]

### Parâmetros:

array1_1d: um array de referência de uma dimensão, cujos itens são examinados para remoção.

array2_1d: um array de uma dimensão, cujos itens são subtraídos do primeiro array de entrada.

casesensitive: Este argumento só é aplicável se os arrays são compostos por strings. (Padrão = False).

### Exemplo:

        Dim a As Variant
        a = SF_Array.Difference(Array("A", "C", "A", "b", "B"), Array("C", "Z", "b"), True)
            ' ("A", "B")

## ExportToTextFile

Escreve todos os itens do array sequencialmente ao arquivo de texto. Se o arquivo já existe, ele é sobrescrito sem aviso prévio.

### Sintaxe:

svc.ExportToTextFile(array_1d: any[0..*], filename: str, [encoding: str]): bool

### Parâmetros:

array_1d: array a ser exportado. Deve conter apenas strings.

filename: nome do arquivo texto onde os dados serão escritos. O nome deve ser expresso em conformidade com o valor atual da propriedade FileNaming do serviço SF_FileSystem.

encoding: conjunto de caracteres a ser usado. Utilize um dos nomes listados na página IANA Character Sets. Note que o LibreOfficeDev pode não implementar todos os conjuntos de caracteres existentes. O padrão é "UTF-8".

### Exemplo:

        SF_Array.ExportToTextFile(Array("A","B","C","D"), "C:\Temp\A short file.txt")

## ExtractColumn

Extrai de um array de duas dimensões uma coluna específica como um novo array.
Seu limitante inferior LBound e superior UBound são idênticos aos valores existentes na primeira dimensão do primeiro array de entrada.

### Sintaxe:

svc.ExtractColumn(array_2d: any[0..*, 0..*], columnindex: int): any[0..*, 0..*]

### Parâmetros:

array_2d: Array a partir do qual extrair.

columnindex: número da coluna a ser extraída. Deve estar no intervalo [LBound, UBound].

### Exemplo:

        'Cria uma matriz 3x3: |1, 2, 3|
        '                      |4, 5, 6|
        '                      |7, 8, 9|
        Dim mat as Variant, col as Variant
        mat = SF_Array.AppendRow(Array(), Array(1, 2, 3))
        mat = SF_Array.AppendRow(mat, Array(4, 5, 6))
        mat = SF_Array.AppendRow(mat, Array(7, 8, 9))
        'Extrai a terceira coluna: |3, 6, 9|
        col = SF_Array.ExtractColumn(mat, 2)

## ExtractRow

Extrair de um array de duas dimensões uma linha específica como um novo array.
Os valores dos limites LBound e UBound são idênticos aos da segunda dimensão do array de entrada.

### Sintaxe:

svc.ExtractRow(array_2d: any[0..*, 0..*], rowindex: int): any[0..*, 0..*]

### Parâmetros:

array_2d: Array a partir do qual extrair.

rowindex: número da linha a ser extraída. Deve estar no intervalo [LBound, UBound].

### Exemplo:

        'Cria uma matriz 3x3: |1, 2, 3|
        '                      |4, 5, 6|
        '                      |7, 8, 9|
        Dim mat as Variant, row as Variant
        mat = SF_Array.AppendRow(Array(), Array(1, 2, 3))
        mat = SF_Array.AppendRow(mat, Array(4, 5, 6))
        mat = SF_Array.AppendRow(mat, Array(7, 8, 9))
        'Extrai a primeira linha: |1, 2, 3|
        row = SF_Array.ExtractRow(mat, 0)

## Flatten

Empilha todos os itens individuais de um array e todos os itens em seus sub-arrays em um novo array sem sub-arrays. Arrays vazios são ignorados e sub-arrays com um número de dimensões maior que um não são achatados.

### Sintaxe:

svc.Flatten(array_1d: any[0..*]): any[0..*]

### Parâmetros:

array_1d: o array pré-existente, pode ser vazio.

### Exemplo:

        Dim a As Variant
        a = SF_Array.Flatten(Array(Array(1, 2, 3), 4, 5))
            ' (1, 2, 3, 4, 5)

Você pode usar o método Flatten juntamente com outros métodos como Append ou Prepend para concatenar um conjunto de arrays de uma dimensão em um único array de uma dimensão.

### Exemplo:

A seguir é apresentado um exemplo de como usar os métodos Flatten e Append para concatenar três arrays.

        'Cria três arrays para este exemplo
        Dim a as Variant, b as Variant, c as Variant
        a = Array(1, 2, 3)
        b = Array(4, 5)
        c = Array(6, 7, 8, 9)
        'Concatena os três arrays em um único array de uma dimensão
        Dim arr as Variant
        arr = SF_Array.Flatten(SF_Array.Append(a, b, c))
        '(1, 2, 3, 4, 5, 6, 7, 8, 9)

## ImportFromCSVFile

Importa os dados contidos em um arquivo CSV (valores separados por vírgulas). A vírgula pode ser substituída por qualquer outro caractere.

O formato CSV aplicável é descrito em IETF Common Format and MIME Type for CSV Files.

Cada linha no arquivo contém um registro completo (quebras de linhas não são permitidas).
Contudo, sequências como \n e \t não são modificadas. Use o método SF_String.Unescape() para gerenciá-las.

Este método retorna um array de duas dimensões cujas linhas correspondem ao registro individual lido de um arquivo e cujas colunas correspondem ao campo do registro. Nenhuma verificação é feita quanto à coerência dos tipos dos campos ao longo das colunas. A biblioteca tentará identificar automaticamente valores do tipo numérico e datas.

Se uma linha contém menos ou mais campos que a primeira linha do arquivo, uma exceção será lançada. Linhas vazias são simplesmente ignoradas. Se o tamanho do arquivo exceder o limite do número de itens, um alerta será lançado e o array será truncado.

### Sintaxe:

svc.ImportFromCSVFile(filename: str, delimiter: str = ',', dateformat: str = ''): any[0..*]

### Parâmetros:

filename: nome do arquivo texto que contém os dados. O nome deve ser expresso em conformidade com o valor atual da propriedade FileNaming do serviço SF_FileSystem.

delimiter: Um caractere único, geralmente uma vírgula, ponto e vírgula ou tabulação (Padrão = ",").

dateformat: Um mecanismo especial manuseia datas quando dateformat é "YYYY-MM-DD", "DD-MM-YYYY" ou "MM-DD-YYYY". O traço (-) pode ser substituído por um ponto (.), uma barra (/) ou um espaço. Outros formatos de data serão ignorados. Datas expressas como uma string vazia "" são consideradas como texto normal.

### Exemplo:

Considere o arquivo CSV "myFile.csv" com o seguinte conteúdo:

Nome,DataDeNascimento,Endereço,Cidade

Ana,2002/03/31,"Rua Sergipe, 123",São Paulo

Eduardo,1998/05/04,"Rua Albert Einstein, 113A",Ribeirão Preto

O exemplo abaixo em Basic e Python lê os conteúdos do arquivo CSV em um objeto Array.

##### Em Basic

        Dim arr As Variant
        arr = SF_Array.ImportFromCSVFile("C:\Temp\meuArquivo.csv", DateFormat := "YYYY/MM/DD")
        MsgBox arr(0, 3) ' Cidade
        MsgBox arr(1, 2) ' Rua Sergipe, 123
        MsgBox arr(1, 3) ' São Paulo

##### Em Python

        from scriptforge import CreateScriptService
        svc = CreateScriptService("Array")
        bas = CreateScriptService("Basic")
        arr = svc.ImportFromCSVFile(r"C:\Temp\meuArquivo.csv", dateformat = "YYYY/MM/DD")
        bas.MsgBox(arr[0][3]) # Cidade
        bas.MsgBox(arr[1][2]) # Rua Sergipe, 123
        bas.MsgBox(arr[1][3]) # São Paulo

## IndexOf

Procura em um array de uma dimensão por um número, uma string ou uma data. Comparações de texto podem ser sensíveis ao caso ou não.
Se o array estiver ordenado, ele deve ser preenchido homogeneamente, o que significa que todos os itens devem ser escalares do mesmo tipo. (Itens Empty e Null não são permitidos).
Os resultados do método são imprevisíveis se o array for anunciado como ordenado, porém não o for.
Uma busca binária é realizada em arrays ordenados. Caso contrário, arrays são simplesmente escaneados de cima a baixo e valores Empty e Null são ignorados.
O método retorna LBound(array de entrada) - 1 se a busca não foi bem sucedida.

### Sintaxe:

svc.IndexOf(array_1d: any[0..*], tofind: any, casesensitive: bool = False, sortorder: str = ''): int

### Parâmetros:

array_1d: O array para ser usado na busca.

tofind: um número, data ou texto a ser procurado.

casesensitive: Apenas para comparação de strings. (Padrão = False).

sortorder: pode ser "ASC" (crescente), "DESC" (decrescente) ou "" (não ordenado). O valor padrão é "".

### Exemplo:

        MsgBox SF_Array.IndexOf(Array("A","B","c","D"), "C", SortOrder := "ASC") ' 2
        MsgBox SF_Array.IndexOf(Array("A","B","c","D"), "C", CaseSensitive := True) ' -1

## Insert

Insere os itens listados como argumentos antes de uma dada posição no array de entrada.
Argumentos são inseridos sem verificação. Cada um deles pode ser tanto um escalar de qualquer tipo como um sub-array.

### Sintaxe:

svc.Insert(array_1d: any[0..*], before: int, arg0: any, [arg1: any] ...): any[0..*]

### Parâmetros:

array_1d: o array pré-existente, pode ser vazio.

before: índice antes do qual os valores serão inseridos. Deve estar no intervalo [LBound, UBound + 1].

arg0, arg1, ...: itens que serão inseridos em array_1d.

### Exemplo:

        Dim a As Variant
        a = SF_Array.Insert(Array(1, 2, 3), 2, "a", "b")
            ' (1, 2, "a", "b", 3)

## InsertSorted

Insere um novo item em um array ordenado.
O array deve ser preenchido homogeneamente, ou seja, todos os seus itens devem ser escalares de um mesmo tipo.
Itens Empty e Null não são permitidos.

### Sintaxe:

svc.InsertSorted(array_1d: any[0..*], item: any, sortorder: str = 'ASC', casesensitive: bool = False): any[0..*]

### Parâmetros:

array_1d: array dentro do qual o valor será inserido.

item: valor escalar a ser inserido, do mesmo tipo que os itens já existentes no array.

sortorder: Pode ser "ASC" (crescente - padrão) ou "DESC" (decrescente).

casesensitive: Apenas para comparação de strings. (Padrão = False).

### Exemplo:

        Dim a As Variant
        a = SF_Array.InsertSorted(Array("A", "C", "a", "b"), "B", CaseSensitive := True)
            ' ("A", "B", "C", "a", "b")

## Intersection

Constrói um conjunto como um array indexado em zero aplicando o operador de "interseção" em dois arrays de entrada. Os itens resultantes estão contidos nos dois arrays.
O array resultante é ordenado de maneira crescente.
Os dois arrays de entrada devem ser preenchidos homogeneamente, ou seja, seus itens devem ser escalares do mesmo tipo. Itens Empty e Null não são permitidos.
Comparação de texto pode ser sensível ao caso ou não.

### Sintaxe:

svc.Intersection(array1_1d: any[0..*], array2_1d: any[0..*], casesensitive: bool = False): any[0..*]

### Parâmetros:

array1_1d: O primeiro array de entrada.

array2_1d: O segundo array de entrada.

casesensitive: Aplicado caso os arrays sejam compostos por strings (Padrão = False).

### Exemplo:

        Dim a As Variant
        a = SF_Array.Intersection(Array("A", "C", "A", "b", "B"), Array("C", "Z", "b"), True)
            ' ("C", "b")

## Join2D

Une dois arrays de duas dimensões com dois delimitadores, um para colunas e outro para linhas.

### Sintaxe:

svc.Join2D(array_2d: any [0..*, 0..*], [columndelimiter: str], [rowdelimiter: str], [quote: str]): str

### Parâmetros:

array_2d: Cada item deve ser um texto, um número, uma data ou um valor booleano.
Datas são transformadas para o formato YYYY-MM-DD hh:mm:ss.
Itens inválidos são substituídos por uma string de comprimento zero.

columndelimiter: Delimitador para cada coluna (Padrão = Tab/Chr(9)).

rowdelimiter: Delimitador para cada linha (Padrão = LineFeed/Chr(10))

quote: Se for True, protege strings com aspas duplas (Padrão = False).

### Exemplo:

        ' arr = | 1, 2, "A", [2020-02-29], 51, 2, "A", [2020-02-29], 5           |
        '       | 6, 7, "this is a string", 9, 106, 7, "this is a string", 9, 10 |
        Dim arr as Variant : arr = Array()
        arr = SF_Array.AppendRow(arr, Array(1, 2, "A", [2020-02-29], 51, 2, "A", [2020-02-29], 5))
        arr = SF_Array.AppendRow(arr, Array(6, 7, "this is a string", 9, 106, 7, "this is a string", 9, 10))
        Dim arrText as String
        arrText = SF_Array.Join2D(arr, ",", "/", False)
        ' 1,2,A,,51,2,A,,5/6,7,this is a string,9,106,7,this is a string,9,10

## Prepend

Concatena os itens passados como argumento no início do array de entrada.

### Sintaxe:

svc.Prepend(array_1d: any[0..*], arg0: any, [arg1: any] ...): any[0..*]

### Parâmetros:

array_1d: o array pré-existente, pode ser vazio.

arg0, arg1, ...: Lista de itens a serem inseridos no início do array_1d.

### Exemplo:

        Dim a As Variant
        a = SF_Array.Prepend(Array(1, 2, 3), 4, 5)
            ' (4, 5, 1, 2, 3)

## PrependColumn

Concatena uma nova coluna ao lado esquerdo de um array de duas dimensões. O array resultante tem os mesmos limitantes inferiores que o array inicial de duas dimensões.

### Sintaxe:

svc.PrependColumn(array_2d: any[0..*, 0..*], column: any[0..*]): any[0..*, 0..*]

### Parâmetros:

array_2d: array pré-existente, pode ser vazio. Se o array tiver uma dimensão, ele é considerado como a última coluna do array resultante de duas dimensões.

column: um array de uma dimensão com a mesma quantidade de itens que a quantidade de linhas em array_2d.

### Exemplo:

        Dim a As Variant, b As variant
        a = SF_Array.PrependColumn(Array(1, 2, 3), Array(4, 5, 6))
            ' ((4, 1), (5, 2), (6, 3))
        b = SF_Array.PrependColumn(Array(), Array(1, 2, 3))
            ' ∀ i ∈ {0 ≤ i ≤ 2} : b(0, i) ≡ i

## PrependRow

Concatena uma nova linha no início de um array de duas dimensões. O array resultante tem os mesmos limitantes inferiores que o array inicial de duas dimensões.

### Sintaxe:

svc.PrependRow(array_2d: any[0..*, 0..*], row: any[0..*]): any[0..*, 0..*]

### Parâmetros:

array_2d: array pré-existente, pode ser vazio. Se o array tiver uma dimensão, ele é considerado como a última linha do array de duas dimensões resultante.

row: Array de uma dimensão com a mesma quantidade de itens que a quantidade de colunas em array_2d.

### Exemplo:

        Dim a As Variant, b As variant
        a = SF_Array.PrependRow(Array(1, 2, 3), Array(4, 5, 6))
            ' ((4, 5, 6), (1, 2, 3))
        b = SF_Array.PrependRow(Array(), Array(1, 2, 3))
            ' ∀ i ∈ {0 ≤ i ≤ 2} : b(i, 0) ≡ i

## RangeInit

Inicializa um array indexado em zero com valores numéricos.

### Sintaxe:

svc.RangeInit(from: num, upto: num, [bystep: num]): num[0..*]

### Parâmetros:

from: Valor do primeiro item.

upto: O último item não deve exceder upto.

bystep: A diferença entre dois itens consecutivos (Padrão = 1).

### Exemplo:

        Dim a As Variant
        a = SF_Array.RangeInit(10, 1, -1)
            ' (10, 9, 8, 7, 6, 5, 4, 3, 2, 1)

## Reverse

Retorna o array de uma dimensão invertido.

### Sintaxe:

svc.Reverse(array_1d: any[0..*]): any[0..*]

### Parâmetros:

array_1d: Array a ser invertido.

### Exemplo:

        Dim a As Variant
        a = SF_Array.Reverse(Array("a", 2, 3, 4))
            ' (4, 3, 2, "a")

## Shuffle

Retorna uma permutação aleatória de um array de uma dimensão.

### Sintaxe:

svc.Shuffle(array_1d: any[0..*]): any[0..*]

### Parâmetros:

array_1d: Array a ser embaralhado.

### Exemplo:

        Dim a As Variant
        a = SF_Array.Shuffle(Array(1, 2, 3, 4))
            ' O array "a" agora está em ordem aleatória, ex: (2, 3, 1, 4)

## Slice

Retorna um subconjunto de um array de uma dimensão.

### Sintaxe:

svc.Slice(array_1d: any[0..*], from: int, [upto: int]): any[0..*]

### Parâmetros:

array_1d: Array a ser fatiado.

from: Índice inferior no array_1d do sub-array a ser extraído (from incluído)

upto: Índice superior no array_1d do sub-array a ser extraído (upto incluído). O valor padrão é o limitante superior do array_1d. Se upto for menor que from então um array vazio é retornado.

### Exemplo:

        Dim a As Variant
        a = SF_Array.Slice(Array(1, 2, 3, 4, 5), 1, 3) ' (2, 3, 4)

## Sort

Ordena um array de uma dimensão em ordem crescente. Comparações de texto podem ou não ser sensíveis ao caso.
O array deve ser preenchido homogeneamente, ou seja, deve possuir apenas valores escalares do mesmo tipo.
Valores Empty e Null são permitidos. Por convenção, Empty é considerado menor que Null que, por sua vez, é menor que qualquer outro escalar.

### Sintaxe:

svc.Sort(array_1d: any[0..*], sortorder: str, casesensitive: bool = False): any[0..*]

### Parâmetros:

array_1d: Array a ser ordenado.

sortorder: Pode ser "ASC" (crescente - padrão) ou "DESC" (decrescente).

casesensitive: Apenas para comparação de strings. (Padrão = False).

### Exemplo:

        Dim a As Variant
        a = SF_Array.Sort(Array("a", "A", "b", "B", "C"), CaseSensitive := True)
            ' ("A", "B", "C", "a", "b")

## SortColumns

Retorna uma permutação das colunas de um array de duas dimensões, ordenado de acordo com os valores nas linhas.
A linha deve ser preenchida homogeneamente, ou seja, deve possuir apenas valores escalares do mesmo tipo.
Valores Empty e Null são permitidos. Por convenção, Empty é considerado menor que Null que, por sua vez, é menor que qualquer outro escalar.

### Sintaxe:

svc.SortColumns(array_2d: any[0..*, 0..*], rowindex: int, sortorder: str, casesensitive: bool = False): any[0..*, 0..*]

### Parâmetros:

array_2d: Array de duas dimensões a ser ordenado.

rowindex: Índice da linha que será usada como referência para ordenar as colunas.

sortorder: Pode ser "ASC" (crescente - padrão) ou "DESC" (decrescente).

casesensitive: Apenas para comparação de strings. (Padrão = False).

### Exemplo:

        ' arr = | 5, 7, 3 |
        '       | 1, 9, 5 |
        '       | 6, 1, 8 |
        Dim arr as Variant : arr = Array(5, 7, 3)
        arr = SF_Array.AppendRow(arr, Array(1, 9, 5))
        arr = SF_Array.AppendRow(arr, Array(6, 1, 8))
        arr = SF_Array.SortColumns(arr, 2, "ASC")
        ' arr = | 7, 5, 3 |
        '       | 9, 1, 5 |
        '       | 1, 6, 8 |

## SortRows

Retorna uma permutação das linhas de um array de duas dimensões, ordenado de acordo com os valores em uma dada coluna.
A coluna deve ser preenchida homogeneamente, ou seja, deve possuir apenas valores escalares do mesmo tipo.
Valores Empty e Null são permitidos. Por convenção, Empty é considerado menor que Null que, por sua vez, é menor que qualquer outro escalar.

### Sintaxe:

svc.SortRows(array_2d: any[0..*, 0..*], columnindex: int, sortorder: str, casesensitive: bool = False): any[0..*, 0..*]

### Parâmetros:

array_2d: Array a ser ordenado.

columnindex: Índice da coluna que será usada como referência para ordenar as linhas.

sortorder: Pode ser "ASC" (crescente - padrão) ou "DESC" (decrescente).

casesensitive: Apenas para comparação de strings. (Padrão = False).

### Exemplo:

        ' arr = | 5, 7, 3 |
        '       | 1, 9, 5 |
        '       | 6, 1, 8 |
        Dim arr as Variant : arr = Array(5, 7, 3)
        arr = SF_Array.AppendRow(arr, Array(1, 9, 5))
        arr = SF_Array.AppendRow(arr, Array(6, 1, 8))
        arr = SF_Array.SortRows(arr, 0, "ASC")
        ' arr = | 1, 9, 5 |
        '       | 5, 7, 3 |
        '       | 6, 1, 8 |

## Transpose

Troca linhas e colunas em um array de duas dimensões.

### Sintaxe:

svc.Transpose(array_2d: any[0..*, 0..*]): any[0..*, 0..*]

### Parâmetros:

array_2d: Array de duas dimensões a ser transposto.

### Exemplo:

        ' arr1 = | 1, 2 |
        '        | 3, 4 |
        '        | 5, 6 |
        arr1 = Array(1, 2)
        arr1 = SF_Array.AppendRow(arr1, Array(3, 4))
        arr1 = SF_Array.AppendRow(arr1, Array(5, 6))
        arr2 = SF_Array.Transpose(arr1)
        ' arr2 = | 1, 3, 5 |
        '        | 2, 4, 6 |
        MsgBox arr2(0, 2) ' 5

## TrimArray

Remove de um array de uma dimensão todas as entradas Null, Empty e de comprimento zero.
Valores string são previamente limpos usando a função Trim() do LibreOfficeDev Basic.

### Sintaxe:

svc.TrimArray(array_1d: any[0..*]): any[0..*]

### Parâmetros:

array_1d: Array a ser aparado.

### Exemplo:

        Dim a As Variant
        a = SF_Array.TrimArray(Array("A", "B", Null, " D "))
            ' ("A", "B", "D")

## Union

Constrói um conjunto como um array indexado em zero aplicando o operador de "união" nos dois arrays de entrada. Os itens resultantes são originados dos dois arrays.
O array resultante é ordenado de maneira crescente.
Os dois arrays de entrada devem ser preenchidos homogeneamente, ou seja, seus itens devem ser escalares do mesmo tipo. Itens Empty e Null não são permitidos.
A comparação de texto pode ou não ser sensível à caixa.

### Sintaxe:

svc.Union(array1_1d: any[0..*], array2_1d: any[0..*], casesensitive: bool = False): any[0..*]

### Parâmetros:

array1_1d: O primeiro array de entrada.

array2_1d: O segundo array de entrada.

casesensitive: Aplicável somente se os arrays são compostos por strings (Padrão = False).

### Exemplo:

        Dim a As Variant
        a = SF_Array.Union(Array("A", "C", "A", "b", "B"), Array("C", "Z", "b"), True)
            ' ("A", "B", "C", "Z", "b")

## Unique

Constrói um conjunto de valores únicos derivados de um array de entrada.
O array de entrada deve ser preenchido homogeneamente, ou seja, todos os itens devem ser escalares do mesmo tipo. Valores Empty e Null não são permitidos.
A comparação textual pode ser sensível ao caso ou não.

### Sintaxe:

svc.Unique(array_1d: any[0..*], casesensitive: bool = False): any[0..*]

### Parâmetros:

array_1d: Array de entrada.

casesensitive: Aplicável somente se o array é composto por strings (Padrão = False).

### Exemplo:

        Dim a As Variant
        a = SF_Array.Unique(Array("A", "C", "A", "b", "B"), CaseSensitive := True)
            '  ("A", "B", "C", "b")

Todas as rotinas ou identificadores do ScriptForge em Basic que possuem o caractere "_" como prefixo são reservadas para uso interno. Elas não devem ser usadas em macros escritas em Basic ou em Python.

Tópicos relacionados

Funções de matriz

Chamar funções do Calc em Macros

Serviço ScriptForge.Dictionary

♥ Doe para nosso projeto! ♥