Serviço ScriptForge.Array (SF_Array)

Conteúdo

# ScriptForge.Array serviço

Fornece um conjunto de métodos para manipular e transformar matrizes unidimensionais (vetores) e bidimensionais (matrizes). Isto inclui operações com conjuntos, ordenação, importação e exportação para ficheiros de texto.

As matrizes com mais de duas dimensões não podem ser utilizadas com os métodos deste serviço, sendo a única exceção o método CountDims, que aceita matrizes com qualquer número de dimensões.

Os elementos de uma matriz podem conter qualquer tipo de valor, incluindo (sub)matrizes.

As matrizes unidimensionais que contêm apenas submatrizes unidimensionais são designadas a seguir por matrizes de dados. São particularmente adequadas para a troca de dados tabulares com scripts Python e folhas de cálculo Calc.

## Chamada de serviço

Antes de utilizar o serviço Array, é necessário carregar a biblioteca ScriptForge utilizando:

        GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

Ao carregar a biblioteca, será criado o objeto SF_Array, que pode ser utilizado para chamar os métodos do serviço Array.

Os trechos de código a seguir mostram as várias formas de chamar métodos no serviço Array (o método Append é utilizado como 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)

Uma vez que o Python possui suporte integrado para listas e tuplas, a maioria dos métodos do serviço Array está disponível apenas para scripts em Basic. A única exceção é o ImportFromCSVFile, que é suportado tanto em Basic como em Python.

Lista de métodos do 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 de matriz a ser considerado. É sempre passado por referência e permanece inalterado. Métodos como Append, Prepend, etc. devolvem um novo objeto de matriz após a sua execução.

## Append

Acrescenta os elementos indicados como argumentos ao final da matriz de entrada.

### Sintaxe:

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

### Parâmetros:

array_1d: O array já existente, que pode estar vazio.

arg0, arg1, ...: Elementos que serão adicionados à array_1d.

### Exemplo:

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

## AppendColumn

Acrescenta uma nova coluna à direita de uma matriz bidimensional. A matriz resultante tem os mesmos limites inferiores que a matriz bidimensional inicial.

### Sintaxe:

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

### Parâmetros:

array_2d: A matriz pré-existente, que pode estar vazia. Se essa matriz tiver apenas uma dimensão, é considerada como a primeira coluna da matriz bidimensional resultante.

coluna: Uma matriz unidimensional com tantos elementos quantas as linhas da 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

Adiciona uma nova linha ao final de uma matriz bidimensional. A matriz resultante tem os mesmos limites inferiores que a matriz bidimensional inicial.

### Sintaxe:

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

### Parâmetros:

array_2d: A matriz pré-existente, que pode estar vazia. Se essa matriz tiver uma dimensão, é considerada como a primeira linha da matriz de duas dimensões resultante.

row: Uma matriz unidimensional com tantos elementos quantas as colunas da 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

Verifique se uma matriz unidimensional contém um determinado número, texto ou data. A comparação de texto pode ser sensível a maiúsculas e minúsculas ou não
As matrizes de entrada ordenadas devem ser preenchidas de forma homogénea, o que significa que todos os elementos devem ser escalares do mesmo tipo (os elementos Empty e Null são proibidos).
O resultado do método é imprevisível quando a matriz é declarada como ordenada e, na realidade, não o está.
É realizada uma pesquisa binária quando a matriz está ordenada; caso contrário, é simplesmente percorrida de cima para baixo e os itens 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: A matriz a analisar.

tofind: Um número, uma data ou uma cadeia de caracteres a procurar.

distingue maiúsculas e minúsculas: Apenas para comparações de cadeias de caracteres (Padrão = False).

sortorder: Pode ser "ASC", "DESC" ou "" (sem ordenação). O valor predefinido é "".

### 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

Converte uma matriz de dados numa matriz Basic.
Uma matriz de dados é uma matriz composta por submatrizes. Quando solicitado, os elementos de saída individuais são reduzidos apenas a cadeias de caracteres ou valores duplos.

O método devolve um escalar, uma matriz unidimensional com índice a partir de zero ou uma matriz bidimensional com índice a partir de zero.
O número de colunas na matriz bidimensional resultante é igual ao número de elementos da primeira submatriz. Se as submatrizes seguintes tiverem um tamanho diferente, as linhas seguintes serão preenchidas 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 composta por submatrizes. A matriz e as submatrizes devem ter indexação a partir de zero.
Normalmente, uma matriz de dados é gerada por

- o método session.ExecuteCalcFunction()

- um script em Python que devolve uma tupla de tuplas

- o método getDataArray() da interface com.sun.star.sheet.XCellRangeData

isrange: Quando True (padrão = False), os elementos são convertidos em cadeias de caracteres ou valores duplos.

fillvalue: Como substituir itens em falta. Valor predefinido = a cadeia 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, de uma matriz unidimensional ou de uma matriz bidimensional.
Uma matriz de dados é uma matriz com indexação a partir de zero, composta por submatrizes com indexação a partir de zero. Se solicitado, os elementos de saída individuais são reduzidos apenas a cadeias de caracteres ou valores duplos.

A matriz de dados devolvida é normalmente utilizada como

- uma tupla de (sub)tuplas passadas a 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 escalar de entrada, matriz 1D ou 2D.

isrange: Quando True (padrão = False), os elementos da matriz são armazenados apenas como cadeias de caracteres (possivelmente vazias) ou valores duplos na matriz de dados.

linhas, colunas: O número de linhas ou colunas da matriz de dados devolvida. Quando excedem os limites de data, preenchem-se com cadeias de caracteres de comprimento zero. Se linhas = 1 e a matriz de entrada for um vetor, a matriz de dados é alinhada horizontalmente (por predefinição, os vetores são alinhados verticalmente). Quando ausente, o tamanho da saída é 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

Armazene o conteúdo de uma matriz de duas colunas num objeto ScriptForge.Dictionary.
A chave será extraída da primeira coluna e o valor da segunda.

### Sintaxe:

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

### Parâmetros:

array_2d: Dados a converter num objeto ScriptForge.Dictionary.

- A primeira coluna deve conter exclusivamente cadeias de caracteres com comprimento superior a zero, em qualquer ordem. Estes valores serão utilizados como rótulos no dicionário.

- A segunda coluna contém os dados que serão associados ao rótulo correspondente 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 com índice a partir de zero composta por submatrizes com índice a partir de zero). Os limites inferiores das matrizes são preservados na saída.

Os elementos individuais são sempre convertidos em cadeias de caracteres ou valores de tipo double, incluindo valores booleanos ou datas.

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

### Sintaxe:

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

### Parâmetros:

dados: O escalar, matriz unidimensional, matriz bidimensional ou matriz de dados de entrada.

direção: O alinhamento do intervalo quando este é um vetor, podendo ser "V" [vertical, predefinição] ou "H" [horizontal].

### 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 uma matriz 1D ou 2D.

### Sintaxe:

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

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

### Parâmetros:

array_nd: A matriz unidimensional ou bidimensional a ser copiada.

### Exemplo:

Uma simples atribuição de um objeto Array irá copiar a sua referência, em vez de criar uma cópia do conteúdo 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
        ' Por isso, alterar os valores em «b» também alterará «a»
        b(0) = 10
        MsgBox a(0) ' 10

Ao utilizar o método Copy, é criada uma cópia de todo o objeto Array. No exemplo abaixo, a e b são objetos diferentes e a alteração dos valores em b não afetará os valores em a.

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

## CountDims

Contar o número de dimensões de uma matriz. O resultado pode ser superior a dois.
Se o argumento não for uma matriz, devolve -1
Se a matriz não estiver inicializada, devolve 0.

### Sintaxe:

svc.CountDims(array_nd: any): int

### Parâmetros:

array_nd: A matriz a analisar.

### Exemplo:

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

## Difference

Cria um conjunto, sob a forma de uma matriz com índice a partir de zero, aplicando o operador de diferença às duas matrizes de entrada. Os elementos resultantes provêm da primeira matriz e não da segunda.
A matriz resultante é ordenada por ordem crescente.
Ambas as matrizes de entrada devem estar preenchidas de forma homogénea; os seus elementos devem ser escalares do mesmo tipo. Vazio e Nulo são proibidos.
A comparação de texto pode ser sensível a maiúsculas e minúsculas ou não.

### Sintaxe:

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

### Parâmetros:

array1_1d: Uma matriz de referência unidimensional, cujos elementos são analisados para remoção.

array2_1d: Uma matriz unidimensional, cujos elementos são subtraídos da primeira matriz de entrada.

distingue maiúsculas e minúsculas: Este argumento só é aplicável se as matrizes forem preenchidas com cadeias de caracteres (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

Grave todos os elementos da matriz sequencialmente num ficheiro de texto. Se o ficheiro já existir, será substituído sem aviso prévio.

### Sintaxe:

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

### Parâmetros:

array_1d: A matriz a exportar. Deve conter apenas cadeias de caracteres.

filename: O nome do ficheiro de texto onde os dados serão gravados. O nome deve ser definido de acordo com a propriedade atual FileNaming do serviço SF_FileSystem.

encoding: O conjunto de caracteres que deve ser utilizado. Utilize um dos nomes indicados em Conjuntos de caracteres da IANA. Note que o LibreOffice pode não suportar todos os conjuntos de caracteres existentes (o valor predefinido é «UTF-8»).

### Exemplo:

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

## ExtractColumn

Extrair de uma matriz bidimensional uma coluna específica como uma nova matriz.
Os seus limites inferior LBound e superior UBound são idênticos aos da primeira dimensão da matriz de entrada.

### Sintaxe:

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

### Parâmetros:

array_2d: A matriz da qual se pretende extrair.

columnindex: O número da coluna a extrair — 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 uma matriz bidimensional uma linha específica como uma nova matriz.
Os seus limites inferior LBound e superior UBound são idênticos aos da segunda dimensão da matriz de entrada.

### Sintaxe:

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

### Parâmetros:

array_2d: A matriz da qual se pretende extrair.

rowindex: O número da linha a extrair — 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

Agrupa todos os elementos individuais de uma matriz e todos os elementos das suas submatrizes numa nova matriz sem submatrizes. As submatrizes vazias são ignoradas e as submatrizes com mais de uma dimensão não são agrupadas.

### Sintaxe:

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

### Parâmetros:

array_1d: O array já existente, que pode estar vazio.

### Exemplo:

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

Pode utilizar o método Flatten em conjunto com outros métodos, como Append ou Prepend, para concatenar um conjunto de matrizes unidimensionais numa única matriz unidimensional.

### Exemplo:

Segue-se um exemplo de como os métodos Flatten e Append podem ser combinados para concatenar três matrizes.

        'Cria três matrizes 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 as três matrizes numa única matriz unidimensional
        Dim arr as Variant
        arr = SF_Array.Flatten(SF_Array.Append(a, b, c))
        '(1, 2, 3, 4, 5, 6, 7, 8, 9)

## ImportFromCSVFile

Importe os dados contidos num ficheiro de valores separados por vírgulas (CSV). A vírgula pode ser substituída por qualquer outro caractere.

O formato CSV aplicável é descrito em Formato Comum da IETF e Tipo MIME para Ficheiros CSV.

Cada linha do ficheiro contém um registo completo (não é permitida a divisão de linhas).
No entanto, sequências como \n, \t, ... permanecem inalteradas. Utilize o método SF_String.Unescape() para as gerir.

O método devolve uma matriz bidimensional cujas linhas correspondem a um único registo lido no ficheiro e cujas colunas correspondem a um campo desse registo. Não é efetuada qualquer verificação quanto à coerência dos tipos de campo entre as colunas. Será feita uma estimativa para identificar os tipos numéricos e de data.

Se uma linha contiver menos ou mais campos do que a primeira linha do ficheiro, será lançada uma exceção. As linhas vazias, no entanto, são simplesmente ignoradas. Se o tamanho do ficheiro exceder o limite de itens (ver no código), é emitido um aviso e a matriz é truncada.

### Sintaxe:

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

### Parâmetros:

nome do ficheiro: O nome do ficheiro de texto que contém os dados. O nome deve ser definido de acordo com a propriedade atual FileNaming do serviço SF_FileSystem.

delimitador: Um único caractere, normalmente uma vírgula, um ponto e vírgula ou um caractere TAB (Padrão = ",").

dateformat: Um mecanismo especial trata as datas quando dateformat é "AAAA-MM-DD", "DD-MM-AAAA" ou "MM-DD-AAAA". O traço (-) pode ser substituído por um ponto (.), uma barra (/) ou um espaço. Outros formatos de data serão ignorados. As datas cujo valor padrão é uma cadeia vazia "" são consideradas como texto normal.

### Exemplo:

Considere o ficheiro CSV «myFile.csv» com o seguinte conteúdo:

Nome,DataDeNascimento,Morada,Cidade

Ana, 31/03/2002, «Rua dos Anjos, 21», Lisboa

Fred, 04/05/1998, «Rue Albert Einstein, 113A», Carcassonne

Os exemplos abaixo, em Basic e Python, leem o conteúdo do ficheiro CSV para um objeto Array.

##### Em Basic

        Dim arr As Variant
        arr = SF_Array.ImportFromCSVFile("C:\Temp\myFile.csv", DateFormat := "YYYY/MM/DD")
        MsgBox arr(0, 3) ' Cidade
        MsgBox arr(1, 2) ' Rua dos Anjos, 21
        MsgBox arr(1, 3) ' Lisboa

##### Em Python

        from scriptforge import CreateScriptService
        svc = CreateScriptService("Array")
        bas = CreateScriptService("Basic")
        arr = svc.ImportFromCSVFile(r"C:\Temp\myFile.csv", dateformat = "YYYY/MM/DD")
        bas.MsgBox(arr[0][3]) # Cidade
        bas.MsgBox(arr[1][2]) # Rua dos Anjos, 21
        bas.MsgBox(arr[1][3]) # Lisboa

## IndexOf

Procura num array unidimensional um número, uma cadeia de caracteres ou uma data. A comparação de texto pode ser sensível a maiúsculas e minúsculas ou não.
Se a matriz estiver ordenada, deve ser preenchida de forma homogénea, o que significa que todos os elementos devem ser escalares do mesmo tipo (elementos Empty e Null são proibidos).
O resultado do método é imprevisível quando a matriz é declarada como ordenada e, na realidade, não o está.
É realizada uma pesquisa binária em matrizes ordenadas. Caso contrário, as matrizes são simplesmente percorridas de cima para baixo e os itens Empty e Null são ignorados.
O método retorna LBound(matriz de entrada) - 1 se a pesquisa não for bem-sucedida.

### Sintaxe:

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

### Parâmetros:

array_1d: A matriz a analisar.

tofind: Um número, uma data ou uma cadeia de caracteres a procurar.

casesensitive: Apenas para comparações de cadeias de caracteres (Padrão = False).

sortorder: Pode ser "ASC", "DESC" ou "" (sem ordenação). O valor predefinido é "

### 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

Inserir, antes de um determinado índice da matriz de entrada, os elementos indicados como argumentos.
Os argumentos são inseridos sem distinção. Cada um deles pode ser um escalar de qualquer tipo ou uma submatriz.

### Sintaxe:

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

### Parâmetros:

array_1d: O array já existente, que pode estar vazio.

before: O índice antes do qual se deve inserir; deve estar no intervalo [LBound, UBound + 1].

arg0, arg1, ...: Elementos que serão inseridos na array_1d.

### Exemplo:

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

## InsertSorted

Inserir um novo elemento numa matriz ordenada, no seu lugar.
A matriz deve ser preenchida de forma homogénea, o que significa que todos os elementos devem ser escalares do mesmo tipo.
Os elementos Empty e Null são proibidos.

### Sintaxe:

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

### Parâmetros:

array_1d: A matriz na qual o valor será inserido.

item: O valor escalar a inserir, do mesmo tipo que os elementos existentes na matriz.

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

casesensitive: Apenas para comparações de cadeias de caracteres (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

Crie um conjunto, sob a forma de uma matriz com índice zero, aplicando o operador de interseção aos dois conjuntos de entrada. Os elementos resultantes estão presentes em ambos os conjuntos.
A matriz resultante é ordenada por ordem crescente.
Ambos os conjuntos de entrada devem ser preenchidos de forma homogénea; por outras palavras, todos os elementos devem ser valores escalares do mesmo tipo. Vazio e Nulo são proibidos.
A comparação de texto pode ser sensível a maiúsculas e minúsculas ou não.

### Sintaxe:

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

### Parâmetros:

array1_1d: A primeira matriz de entrada.

array2_1d: A segunda matriz de entrada.

distingue maiúsculas e minúsculas: Aplica-se a matrizes preenchidas com elementos de texto (Predefiniçã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

Junte uma matriz bidimensional utilizando dois delimitadores: um para as colunas e outro para as linhas.

### Sintaxe:

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

### Parâmetros:

array_2d: Cada elemento deve ser texto, um número, uma data ou um valor booleano.
As datas são convertidas para o formato AAAA-MM-DD hh:mm:ss.
Os elementos inválidos são substituídos por uma cadeia de caracteres de comprimento zero.

columndelimiter: Delimita cada coluna (padrão = Tab/Chr(9)).

rowdelimiter: Delimita cada linha (padrão = LineFeed/Chr(10))

citação: Se True, protege as cadeias de caracteres com aspas duplas. O valor predefinido é 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

Adicione no início da matriz de entrada os elementos indicados como argumentos.

### Sintaxe:

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

### Parâmetros:

array_1d: O array já existente, que pode estar vazio.

arg0, arg1, ...: Uma lista de elementos a acrescentar no início de array_1d.

### Exemplo:

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

## PrependColumn

Adiciona uma nova coluna à esquerda de uma matriz bidimensional. A matriz resultante tem os mesmos limites inferiores que a matriz bidimensional inicial.

### Sintaxe:

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

### Parâmetros:

array_2d: A matriz pré-existente, que pode estar vazia. Se essa matriz tiver uma dimensão, é considerada como a última coluna da matriz de duas dimensões resultante.

coluna: Uma matriz unidimensional com tantos elementos quantas as linhas da 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

Insere uma nova linha no início de uma matriz bidimensional. A matriz resultante tem os mesmos limites inferiores que a matriz bidimensional inicial.

### Sintaxe:

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

### Parâmetros:

array_2d: A matriz pré-existente, que pode estar vazia. Se essa matriz tiver uma dimensão, é considerada como a última linha da matriz bidimensional resultante.

row: Uma matriz unidimensional que contém tantos elementos quantas as colunas da 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

Inicializar uma nova matriz com índice zero contendo 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 elementos sucessivos (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

Devolve o array unidimensional de entrada invertida.

### Sintaxe:

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

### Parâmetros:

array_1d: O array a inverter.

### Exemplo:

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

## Shuffle

Devolve uma permutação aleatória de uma matriz unidimensional.

### Sintaxe:

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

### Parâmetros:

array_1d: O array a baralhar.

### Exemplo:

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

## Slice

Devolve um subconjunto de uma matriz unidimensional.

### Sintaxe:

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

### Parâmetros:

array_1d: A matriz a ser fragmentada.

from: O índice inferior em array_1d da submatriz a extrair (from incluído)

upto: O índice superior em array_1d da submatriz a extrair (upto incluído). O valor predefinido é o limite superior de array_1d. Se upto < from, a matriz devolvida fica vazia.

### Exemplo:

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

## Sort

Ordenar uma matriz unidimensional por ordem crescente ou decrescente. As comparações de texto podem ser sensíveis a maiúsculas e minúsculas ou não.
A matriz deve ser preenchida de forma homogénea, o que significa que os elementos devem ser escalares do mesmo tipo.
Empty e Null são permitidos. Convencionalmente, Empty < Null < qualquer outro valor escalar.

### Sintaxe:

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

### Parâmetros:

array_1d: A matriz a ordenar.

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

casesensitive: Apenas para comparações de cadeias de caracteres (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 uma matriz bidimensional, ordenada de acordo com os valores de uma determinada linha.
A linha deve estar preenchida de forma homogénea, o que significa que todos os elementos devem ser escalares do mesmo tipo.
São permitidos elementos Empty e Null. Convencionalmente, Empty < Null < qualquer outro valor escalar.

### Sintaxe:

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

### Parâmetros:

array_2d: A matriz bidimensional a ordenar.

rowindex: O índice da linha que será utilizado como referência para ordenar as colunas.

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

casesensitive: Apenas para comparações de cadeias de caracteres (Predefiniçã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 uma matriz bidimensional, ordenadas de acordo com os valores de uma determinada coluna.
A coluna deve estar preenchida de forma homogénea; por isso, todos os elementos devem ser escalares do mesmo tipo.
São permitidos elementos Empty e Null. Convencionalmente, Empty < Null < qualquer outro valor escalar.

### Sintaxe:

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

### Parâmetros:

array_2d: A matriz a ordenar.

columnindex: O índice da coluna que será utilizado como referência para ordenar as linhas.

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

distingue maiúsculas e minúsculas: Apenas para comparações de cadeias de caracteres (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 as linhas e colunas de uma matriz bidimensional.

### Sintaxe:

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

### Parâmetros:

array_2d: A matriz bidimensional a transpor.

### 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

Remova de uma matriz unidimensional todas as entradas Null, Empty e de comprimento zero.
Os elementos de tipo String são aparados com a função Trim() do LibreOffice Basic.

### Sintaxe:

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

### Parâmetros:

array_1d: A matriz a ser recortada.

### Exemplo:

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

## Union

Cria um conjunto, sob a forma de uma matriz com índice a partir de zero, aplicando o operador de união às duas matrizes de entrada. Os elementos resultantes provêm de qualquer uma das duas matrizes.
A matriz resultante é ordenada por ordem crescente.
Ambas as matrizes de entrada devem estar preenchidas de forma homogénea; os seus elementos devem ser escalares do mesmo tipo. Empty e Null são proibidos.
A comparação de texto pode ser sensível a maiúsculas e minúsculas ou não.

### Sintaxe:

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

### Parâmetros:

array1_1d: A primeira matriz de entrada.

array2_1d: A segunda matriz de entrada.

casesensitive: Aplicável apenas se as matrizes forem preenchidas com cadeias de caracteres (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

Crie um conjunto de valores únicos derivados da matriz de entrada.
A matriz de entrada deve ser preenchida de forma homogénea; os seus elementos devem ser escalares do mesmo tipo. Não são permitidos elementos Empty nem Null.
A comparação de texto pode ou não distinguir maiúsculas de minúsculas.

### Sintaxe:

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

### Parâmetros:

array_1d: A matriz de entrada.

casesensitive: Aplicável apenas se a matriz for preenchida com cadeias de caracteres (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 Basic que tenham o caractere de sublinhado «_» como prefixo estão reservados para uso interno. Não se destinam a ser utilizados em macros do Basic ou em scripts Python.

Tópicos relacionados

Funções de Matriz

Utilização de funções do Calc em macros

ScriptForge.Dicionário serviço

Necessitamos da sua ajuda!