Serviço ScriptForge.Array (SF_Array)

Conteúdo
Índice 🔎︎

# 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). Inclui operações de conjuntos, ordenação, 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 Array podem conter valores de qualquer tipo, incluindo sub-arrays.

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

          SF_Array.Append(...)

          Dim arr    :    arr = SF_Array
          arr.Append(...)

          Dim arr    :    arr = CreateScriptService("Array")
          arr.Append(...)

O método CreateScriptService está disponível apenas depois que você tiver carregado a biblioteca ScriptForge.

Métodos
Append AppendColumn AppendRow Contains ConvertToDictionary 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:

          SF_Array.Append(Array_1D As Variant, arg0 As Variant, [arg1 As Variant], ...) As Variant

### Parâmetros:

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

arg0, ... : uma lista de itens a serem concatenados ao Array_1D.

### Exemplo:

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

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

          SF_Array.AppendColumn(Array_2D As Variant, New_Column As Variant) As Variant

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

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

### Exemplo:

          Sub Example_AppendColumn()
          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
          End Sub

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

          SF_Array.AppendRow(Array_2D As Variant, Row As Variant) As Variant

### 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 : array de uma dimensão com uma quantidade de itens igual à quantidade de colunas em Array_2D.

### Exemplo:

          Sub Example_AppendRow()
          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
          End Sub

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

          SF_Array.Contains(Array_1D, ToFind As Variant, [CaseSensitive As Boolean], [SortOrder As String]) As Boolean

### 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 : "ASC", "DESC" ou "" (= não ordenado, padrão)

### Exemplo:

          Sub Example_Contains()
          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
          End Sub

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

          SF_Array.ConvertToDictionary(Array_2D As Variant) As Variant

### Parâmetros:

Array_1D : a primeira coluna deve conter exclusivamente strings com comprimento maior que 0, em qualquer ordem.

### Exemplo:

          Sub Example_ConvertToDictionary()
          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
          End Sub

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

          SF_Array.CountDims(Array_ND As Variant) As Integer

### Parâmetros:

Array_ND : array a ser examinado.

### Exemplo:

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

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

          SF_Array.Difference(Array1_1D As Variant, Array2_1D As Variant[, CaseSensitive As Boolean]) As Variant

### 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 : Somente se os arrays são compostos por strings, padrão = False.

### Exemplo:

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

## ExportToTextFile

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

### Sintaxe:

          SF_Array.ExportToTextFile(Array_1D As Variant, FileName As String, [Encoding As String]) As Boolean

### Parâmetros:

Array_1D : Array a ser exportado. Deve conter apenas strings.

FileName : Nome do arquivo texto contendo os dados. O nome é expresso usando a propriedade atual FileNaming do serviço SF_FileSystem. O padrão é = "any" (tanto o formato URL como o formato do sistema operacional são admissíveis).

Encoding : Conjunto de caracteres a ser usado. Utilize um dos nomes listados em Conjunto de caracteres IANA. Note que o LibreOffice pode não implementar todos os conjuntos de caracteres existentes. O padrão é "UTF-8".

### Exemplo:

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

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

          SF_Array.ExtractColumn(Array_2D As Variant, ColumnIndex As Long) As Variant

### Parâmetros:

Array_2D : Array a partir do qual extrair.

ColumnIndex : Número da coluna da qual extrair. Deve estar no intervalo [LBound, UBound].

### Exemplo:

          Sub Example_ExtractColumn
             '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)
          End Sub

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

          SF_Array.ExtractRow(Array_2D As Variant, RowIndex As Long) As Variant

### Parâmetros:

Array_2D : Array a partir do qual extrair.

RowIndex : Número da linha da qual extrair. Deve estar no intervalo [LBound, UBound].

### Exemplo:

          Sub Example_ExtractRow
             '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)
          End Sub

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

          SF_Array.Flatten(Array_1D As Variant) As Variant

### Parâmetros:

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

### Exemplo:

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

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.

          Sub Concatenate_Example
             '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)
          End Sub

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

          SF_Array.ImportFromCSVFile(FileName As String, [Delimiter As String], [DateFormat As String]) As Variant

### Parâmetros:

FileName : Nome do arquivo texto contendo os dados. O nome é expresso usando a propriedade atual FileNaming do serviço SF_FileSystem. O padrão é = "any" (tanto o formato URL como o formato do sistema operacional são admissíveis).

Delimiter : Um caracter ú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 com padrão "" são consideradas como texto.

### Exemplo:

Dado este arquivo CSV:

          Name,DateOfBirth,Address,City
          Anna,2002/03/31,"Rue de l'église, 21",Toulouse
          Fred,1998/05/04,"Rue Albert Einstein, 113A",Carcassonne

          Sub Example_ImportFromCSVFile()
          Dim a As Variant
              a = SF_Array.ImportFromCSVFile("C:\Temp\myFile.csv", DateFormat := "YYYY/MM/DD")
              MsgBox a(0, 3)    ' City
              MsgBox TypeName(a(1, 2))    ' Date
              MsgBox a(2, 2)    ' Rue Albert Einstein, 113A
          End Sub

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

          SF_Array.IndexOf(Array_1D, ToFind As Variant, [CaseSensitive As Boolean], [SortOrder As String]) As Long

### 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 : "ASC", "DESC" ou "" (= não ordenado, padrão)

### Exemplo:

          Sub Example_IndexOf()
              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
          End Sub

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

          SF_Array.Insert(Array_1D As Variant, Before As Long, arg0 As Variant, [arg1 As Variant], ...) As Variant

### 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, ... : Lista de itens a serem inseridos em Array_1D.

### Exemplo:

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

## InsertSorted

Inserir em seu lugar 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:

          SF_Array.InsertSorted(Array_1D As Variant, Item As Variant, SortOrder As String, CaseSensitive As Boolean) As Variant

### Parâmetros:

Array_1D : O array a ser ordenado.

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

SortOrder : "ASC" (padrão) ou "DESC".

CaseSensitive : Apenas para comparação de strings, padrão = False.

### Exemplo:

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

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

          SF_Array.Intersection(Array1_1D As Variant, Array2_1D As Variant[, CaseSensitive As Boolean]) As Variant

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

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

## Join2D

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

### Sintaxe:

          SF_Array.Join2D(Array_2D As Variant, ColumnDelimiter As String, RowDelimiter As String, Quote As Boolean) As String

### Parâmetros:

Array_2D : Cada item deve ser um texto, um número, uma data ou um valor booleano.
Datas são transfornadas 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, proteje strings com aspas duplas. Padrão = False.

### Exemplo:

          Sub Example_Join2D()
          -                     | 1, 2, "A", [2020-02-29], 5      |
          -    SF_Array.Join_2D(| 6, 7, "this is a string", 9, 10 |, ",", "/")
          -            ' "1,2,A,2020-02-29 00:00:00,5/6,7,this is a string,9,10"
          End Sub

## Prepend

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

### Sintaxe:

          SF_Array.Prepend(Array_1D As Variant, arg0 As Variant, [arg1 As Variant], ...) As Variant

### Parâmetros:

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

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

### Exemplo:

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

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

          SF_Array.PrependColumn(Array_2D As Variant, Column As Variant) As Variant

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

          Sub Example_PrependColumn()
          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
          End Sub

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

          SF_Array.PrependRow(Array_2D As Variant, Row As Variant) As Variant

### 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 : um array de uma dimensão com a mesma quantidade de itens que a quantidade de linhas em Array_2D.

### Exemplo:

          Sub Example_PrependRow()
          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
          End Sub

## RangeInit

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

### Sintaxe:

          SF_Array.RangeInit(From As [number], UpTo As [number] [, ByStep As [number]]) As Variant

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

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

## Reverse

Retorna o array de uma dimensão invertido.

### Sintaxe:

          SF_Array.Reverse(Array_1D As Variant) As Variant

### Parâmetros:

Array_1D : Array a ser invertido.

### Exemplo:

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

## Shuffle

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

### Sintaxe:

          SF_Array.Shuffle(Array_1D As Variant) As Variant

### Parâmetros:

Array_1D : Array a ser embaralhado.

### Exemplo:

          Sub Example_Shuffle()
          Dim a As Variant
              a = SF_Array.Shuffle(Array(1, 2, 3, 4))
                  ' Imprevisível
          End Sub

## Slice

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

### Sintaxe:

          SF_Array.Slice(Array_1D As Variant, From As Long, [UpTo As Long]) As Variant

### 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). Padrão = Limitante superior do Array_1D. Se UpTo for menor que From então um array vazio é retornado.

### Exemplo:

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

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

          SF_Array.Sort(Array_1D As Variant, SortOrder As String, CaseSensitive As Boolean) As Variant

### Parâmetros:

Array_1D : O array a ser ordenado.

SortOrder : "ASC" (padrão) ou "DESC".

CaseSensitive : Apenas para comparação de strings, padrão = False.

### Exemplo:

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

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

          SF_Array.SortColumns(Array_1D As Variant, RowIndex As Long, SortOrder As String, CaseSensitive As Boolean) As Variant

### Parâmetros:

Array_1D : O array a ser ordenado.

RowIndex : O índice da linha para ordenar as colunas.

SortOrder : "ASC" (padrão) ou "DESC".

CaseSensitive : Apenas para comparação de strings, padrão = False.

### Exemplo:

          Sub Example_SortColumns()
          -                         | 5, 7, 3 |            ' | 7, 5, 3 |
          -    SF_Array.SortColumns(| 1, 9, 5 |, 2, "ASC") ' | 9, 1, 5 |
          -                         | 6, 1, 8 |            ' | 1, 6, 8 |
          End Sub

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

          SF_Array.SortRows(Array_1D As Variant, ColumnIndex As Long, SortOrder As String, CaseSensitive As Boolean) As Variant

### Parâmetros:

Array_1D : O array a ser ordenado.

RowIndex : O índice da coluna para ordenar as linhas.

SortOrder : "ASC" (padrão) ou "DESC".

CaseSensitive : Apenas para comparação de strings, padrão = False.

### Exemplo:

          Sub Example_SortRows()
          -                      | 5, 7, 3 |            ' | 1, 9, 5 |
          -    SF_Array.SortRows(| 1, 9, 5 |, 2, "ASC") ' | 5, 7, 3 |
          -                      | 6, 1, 8 |            ' | 6, 1, 8 |
          End Sub

## Transpose

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

### Sintaxe:

          SF_Array.Transpose(Array_2D As Variant) As Variant

### Parâmetros:

Array_2D : Array a ser transposto.

### Exemplo:

          Sub Example_Transpose()
          -                       | 1, 2 |  ' | 1, 3, 5 |
          -    SF_Array.Transpose(| 3, 4 |) ' | 2, 4, 6 |
          -                       | 5, 6 |
          End Sub

## 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 LibreOffice Basic.

### Sintaxe:

          SF_Array.TrimArray(Array_1D As Variant) As Variant

### Parâmetros:

Array_1D : O array para ser usado na busca.

### Exemplo:

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

## 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.
Comparação de texto pode ser sensível ao caso ou não.

### Sintaxe:

          SF_Array.Union(Array1_1D As Variant, Array2_1D As Variant[, CaseSensitive As Boolean]) As Variant

### Parâmetros:

Array1_1D : O primeiro array de entrada.

Array2_1D : O segundo array de entrada.

CaseSensitive : Somente se os arrays são compostos por strings, padrão = False.

### Exemplo:

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

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

          SF_Array.Unique(Array_1D As Variant, CaseSensitive As Boolean]) As Variant

### Parâmetros:

Array1_1D : Array de entrada.

CaseSensitive : Somente se o array é composto por strings, padrão = False.

### Exemplo:

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

Todas as rotinas básicas ou identificadores do ScriptForge que possuem o caractere "_" como prefixo são reservados apenas para uso interno. Elas não devem ser usadas em macros Basic.

Tópicos relacionados

Funções de matriz

Chamar funções do Calc

Serviço ScriptForge.Dictionary