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.

Items 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(...)
   
note

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


tip

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
   
tip

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
   
warning

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.


♥ Doe para nosso projeto! ♥