Usługa ScriptForge.Array (SF_Array)

Spis treści

# Usługa ScriptForge.Array

Udostępnia zbiór metod służących do manipulowania i przekształcania tablic jednego wymiaru (wektorów) i tablic dwuwymiarowych (macierzy). Obejmuje to operacje na zestawach, sortowanie, importowanie i eksportowanie do plików tekstowych.

Tablice o więcej niż dwóch wymiarach nie mogą być używane z metodami w tej usłudze, jedynym wyjątkiem jest metoda CountDims, która akceptuje tablice o dowolnej liczbie wymiarów.

Elementy tablicy mogą zawierać dowolny typ wartości, w tym (pod)tablice.

Tablice jednowymiarowe zawierające tylko jednowymiarowe podtablice nazywane są poniżej tablicami danych. Są one szczególnie przydatne do wymiany danych tabelarycznych ze skryptami języka Python i arkuszami programu Calc.

## Wywoływanie usługi

Przed użyciem usługi Array należy załadować bibliotekę ScriptForge z:

        GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

Załadowanie biblioteki spowoduje utworzenie obiektu SF_Array, który można użyć do wywołania metod w usłudze Array.

Poniższe fragmenty kodu przedstawiają różne sposoby wywoływania metod w usłudze Array (jako przykładu użyto metody Append):

        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)

Ponieważ Python ma wbudowaną obsługę list i krotek, większość metod w usłudze Array jest dostępna tylko dla skryptów Basic. Jedynym wyjątkiem jest ImportFromCSVFile, który jest obsługiwany zarówno w języku Basic, jak i Python.

Lista metod w usłudze 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

Pierwszym argumentem większości metod jest obiekt tablicy, który należy wziąć pod uwagę. Zawsze jest przekazywany przez referencję i pozostawiany bez zmian. Metody takie jak Append, Prepend itp. zwracają po wykonaniu nowy obiekt tablicy.

## Append

Dołącza elementy wymienione jako argumenty na końcu tablicy wejściowej.

### Składnia:

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

### Parametry:

array_1d: istniejąca tablica może być pusta.

arg0, arg1, ...: elementy, które zostaną dołączone do array_1d.

### Przykład:

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

## AppendColumn

Dołącza nową kolumnę po prawej stronie tablicy dwuwymiarowej. Otrzymana tablica ma takie same dolne granice jak początkowa tablica dwuwymiarowa.

### Składnia:

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

### Parametry:

array_2d: istniejąca wcześniej tablica może być pusta. Jeśli ta tablica ma tylko jeden wymiar, jest uważana za pierwszą kolumnę wynikowej tablicy dwuwymiarowej.

column: jednowymiarowa tablica zawierająca tyle elementów, ile jest wierszy w array_2d.

### Przykład:

        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

Dołącz nowy wiersz na dole dwuwymiarowej tablicy. Otrzymana tablica ma takie same dolne granice jak początkowa tablica dwuwymiarowa.

### Składnia:

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

### Parametry:

array_2d: istniejąca wcześniej tablica może być pusta. Jeśli ta tablica ma 1 wymiar, jest traktowana jako pierwszy wiersz wynikowej tablicy dwuwymiarowej.

row: jednowymiarowa tablica zawierająca tyle elementów, ile jest kolumn w array_2d.

### Przykład:

        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

Sprawdź, czy jednowymiarowa tablica zawiera określoną liczbę, tekst lub datę. Porównanie tekstu może uwzględniać wielkość liter lub nie.
Posortowane tablice wejściowe muszą być wypełnione jednorodnie, co oznacza, że wszystkie elementy muszą być skalarami tego samego typu (elementy Empty i Null są zabronione).
Rezultat metody jest nieprzewidywalny, gdy tablica jest ogłoszona jako posortowana, aw rzeczywis tości tak nie jest.
Wyszukiwanie binarne jest wykonywane, gdy tablica jest sortowana, w przeciwnym razie jest po prostu skanowana od góry do dołu, a elementy Empty i Null są ignorowane.

### Składnia:

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

### Parametry:

array_1d: tablica do przeskanowania.

tofind: liczba, data lub ciąg znaków do znalezienia.

casesensitive: tylko dla porównań ciągów znaków (domyślnie = False).

sortorder: może to być "ASC", "DESC" lub "" (bez sortowania). Wartość domyślna to "".

### Przykład:

        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

Konwertuj tablicę danych na tablicę Basic.
Tablica danych to tablica podtablic. Na żądanie poszczególne elementy wyjściowe są redukowane wyłącznie do ciągów znaków lub liczb zmiennoprzecinkowych (tzw. double).

Metoda zwraca skalar, tablicę jednowymiarową z zerami lub tablicę dwuwymiarową z zerami.
Liczba kolumn w wynikowej tablicy dwuwymiarowej jest równa liczbie elementów w pierwszej podtablicy. Jeśli kolejne podtablice mają inny rozmiar, kolejne wiersze zostaną uzupełnione argumentem fillvalue lub obcięte.

### Składnia:

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

### Parametry:

dataarray: tablica podtablic. Tablice i podtablice muszą być zerowe.
Zwykle tablica danych jest wyprowadzana przez

- metodę session.ExecuteCalcFunction()

- skrypt Pythona zwracający krotkę krotek

- Metoda getDataArray() z interfejsucom.sun.star.sheet.XCellRangeData

isrange: gdy wartość wynosi True (domyślnie = False), elementy są konwertowane na ciągi znaków lub liczby zmiennoprzecinkowe.

fillvalue: jak zastąpić brakujące elementy. Domyślnie = pusty ciąg.

### Przykład:

        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

Utwórz tablicę danych ze skalara, tablicy 1-wymiarowej lub tablicy 2-wymiarowej.
Tablica danych to tablica zerowa podtablic. Na żądanie poszczególne elementy wyjściowe są redukowane wyłącznie do ciągów znaków lub liczb zmiennoprzecinkowych.

Zwrócona tablica danych jest zazwyczaj używana jako

- krotka (pod)krotek przekazana do skryptu Pythona

- argument metody setDataArray() z interfejsu com.sun.star.sheet.XCellRangeData

### Składnia:

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

### Parametry:

data: skalar danych wejściowych, tablica 1D lub 2D.

isrange: gdy wartość wynosi True (domyślnie = False), elementy tablicy są przechowywane wyłącznie jako (być może puste) ciągi znaków lub liczby zmiennoprzecinkowe w tablicy danych.

rows, columns: liczba wierszy lub kolumn zwróconej tablicy danych. Jeśli przekraczają one limit data, wypełniaj ciągami o zerowej długości. Jeśli rows = 1, a tablica wejściowa jest wektorem, tablica danych jest wyrównywana poziomo (domyślnie wektory są wyrównywane pionowo). W przypadku braku tego parametru rozmiar danych wyjściowych jest określany na podstawie tablicy wejściowej.

### Przykład:

        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

Przechowuj zawartość dwukolumnowej tablicy w obiekcie ScriptForge.Dictionary.
Klucz zostanie wyodrębniony z pierwszej kolumny, element z drugiej.

### Składnia:

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

### Parametry:

array_2d: dane do przekonwertowania na obiekt ScriptForge.Dictionary.

- Pierwsza kolumna musi zawierać wyłącznie łańcuchy o długości większej od zera, w dowolnej kolejności. Te wartości będą używane jako etykiety w słowniku.

- Druga kolumna zawiera dane, które zostaną skojarzone z odpowiednią etykietą w słowniku.

### Przykład:

        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

Utwórz prawidłową zawartość zakresu komórek ze skalara, tablicy 1-wymiarowej, tablicy 2-wymiarowej lub tablicy danych (tablica danych to tablica zerowa podtablic zerowych). Dolne granice tablic są zachowywane w wynikach.

Poszczególne elementy są zawsze redukowane do ciągów znaków lub liczb zmiennoprzecinkowych, w tym wartości logicznych i dat.

Zwrócony skalar lub tablica 2D jest prawidłowym argumentem metody session.ExecuteCalcFunction(). Jest to szczególnie przydatne w kontekście [złożonych] funkcji tablicowych.

### Składnia:

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

### Parametry:

data: skalar danych wejściowych, tablica 1D, tablica 2D lub tablica danych.

direction: wyrównanie zakresu, gdy jest to wektor, „V” (pionowy, domyślny) lub „H” (poziomy).

### Przykład:

        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))
        matrix = SF_Array.AppendRow(matrix, Array(7, 8, -9))
        result = session.ExecuteCalcFunction("ABS", SF_Array.ConvertToRange(matrix))
        MsgBox result(2)(2) ' 9 - result is a data array

## Copy

Tworzy kopię jednowymiarowej lub dwuwymiarowej tablicy.

### Składnia:

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

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

### Parametry:

array_nd: jednowymiarowa lub dwuwymiarowa tablica do skopiowania.

### Przykład:

Proste przypisanie obiektu Array spowoduje skopiowanie jego odwołania zamiast tworzenia kopii zawartości obiektu. Zobacz przykład poniżej:

        Dim a as Variant, b as Variant
        a = Array(1, 2, 3)
        ' Poniższe zadanie zostało wykonane przez odniesienie
        b = a
        ' Dlatego zmiana wartości w "b" zmieni również "a"
        b(0) = 10
        MsgBox a(0) ' 10

Za pomocą metody Copy tworzona jest kopia całego obiektu Array. W poniższym przykładzie a i b to różne obiekty, a zmiana wartości w b nie wpłynie na wartości w a.

        Dim a as Variant, b as Variant
        a = Array(1, 2, 3)
        ' Tworzy kopię "a" przy użyciu metody "Copy".
        b = SF_Array.Copy(a)
        b(0) = 10
        MsgBox a(0) ' 1

## CountDims

Policz liczbę wymiarów tablicy. Wynik może być większy niż dwa.
Jeśli argument nie jest tablicą, zwraca -1
Jeśli tablica nie jest zainicjowana, zwraca 0.

### Składnia:

svc.CountDims(array_nd: any): int

### Parametry:

array_nd: tablica do sprawdzenia.

### Przykład:

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

## Difference

Stosuje operator różnicy do dwóch pól wejściowych, aby utworzyć zestaw tablic liczonych od 0. Wynikowe elementy pochodzą z pierwszej tablicy, a nie z drugiej.
Otrzymana tablica jest sortowana w porządku rosnącym.
Obie tablice wejściowe muszą być wypełnione jednorodnie, tzn. ich wpisy muszą być skalarami tego samego typu. Wartości Empty i Null są niedozwolone.
Porównania tekstu mogą uwzględniać wielkość liter lub nie.

### Składnia:

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

### Parametry:

array1_1d: jednowymiarowa tablica referencyjna, której elementy są sprawdzane pod kątem usunięcia.

tablica2_1d: jednowymiarowa tablica, której elementy są odejmowane od pierwszej tablicy wejściowej.

casesensitive: ten argument ma zastosowanie tylko wtedy, gdy tablice są wypełnione ciągami znaków (domyślnie = False).

### Przykład:

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

## ExportToTextFile

Zapisz kolejno wszystkie elementy tablicy do pliku tekstowego. Jeśli plik już istnieje, zostanie nadpisany bez ostrzeżenia.

### Składnia:

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

### Parametry:

array_1d: tablica do wyeksportowania. Musi zawierać tylko ciągi znaków.

filename: nazwa pliku tekstowego, w którym zostaną zapisane dane. Nazwa musi być wyrażona zgodnie z aktualną właściwością FileNaming usługi SF_FileSystem.

encoding: zestaw znaków, który powinien być używany. Użyj jednej z nazw wymienionych w zestawach znaków IANA. Należy pamiętać, że LibreOffice może nie implementować wszystkich istniejących zestawów znaków (domyślnie jest to "UTF-8").

### Przykład:

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

## ExtractColumn

Wyodrębnij z dwuwymiarowej tablicy określoną kolumnę jako nową tablicę.
Jej dolne LBound i górne UBound granice są identyczne z pierwszym wymiarem tablicy wejściowej.

### Składnia:

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

### Parametry:

array_2d: tablica, z której ma zostać wyodrębniona.

columnindex: numer kolumny do wyodrębnienia – musi mieścić się w przedziale [LBound, UBound].

### Przykład:

        ' Tworzy macierz 3 × 3: |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))
        ' Wyodrębnia trzecią kolumnę: |3, 6, 9|
        col = SF_Array.ExtractColumn(mat, 2)

## ExtractRow

Wyodrębnij z dwuwymiarowej tablicy określony wiersz jako nową tablicę.
Jego dolna granica LBound i górna UBound są identyczne z granicami drugiego wymiaru tablicy wejściowej.

### Składnia:

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

### Parametry:

array_2d: tablica, z której ma zostać wyodrębniona.

rowindex: numer wiersza do wyodrębnienia – musi mieścić się w przedziale [LBound, UBound].

### Przykład:

        ' Tworzy macierz 3 × 3: |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))
        ' Wyodrębnia pierwszy wiersz: |1, 2, 3|
        row = SF_Array.ExtractRow(mat, 0)

## Flatten

Ułóż wszystkie pojedyncze elementy tablicy i wszystkie elementy w jej podtablicach w jedną nową tablicę bez podtablic. Puste podtablice są ignorowane, a podtablice o liczbie wymiarów większej niż jeden nie są spłaszczane.

### Składnia:

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

### Parametry:

array_1d: istniejąca tablica może być pusta.

### Przykład:

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

Możesz użyć metody Flatten wraz z innymi metodami, takimi jak Append lub Prepend, aby połączyć zestaw jednowymiarowych tablic w pojedynczą tablicę jednowymiarową.

### Przykład:

Poniżej znajduje się przykład łączenia metod Flatten i Append w celu połączenia trzech tablic.

        ' Tworzy trzy tablice dla tego przykładu
        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)
        ' Łączy trzy tablice w jedną tablicę jednowymiarową
        Dim arr as Variant
        arr = SF_Array.Flatten(SF_Array.Append(a, b, c))
        '(1, 2, 3, 4, 5, 6, 7, 8, 9)

## ImportFromCSVFile

Zaimportuj dane zawarte w pliku z wartościami rozdzielanymi przecinkami (CSV). Przecinek można zastąpić dowolnym znakiem.

Obowiązujący format CSV jest opisany w artykule IETF Common Format and MIME Type for CSV Files.

Każdy wiersz w pliku zawiera pełny rekord (podział wiersza nie jest dozwolony).
Jednakże sekwencje takie jak \n, \t, ... pozostają niezmienione. Użyj metody SF_String.Unescape(), aby nimi zarządzać.

Metoda zwraca dwuwymiarową tablicę, której wiersze odpowiadają pojedynczemu rekordowi odczytanemu w pliku, a kolumny odpowiadają polu rekordu. Nie sprawdza się spójności typów pól w kolumnach. Zostanie dokonane najlepsze odgadnięcie w celu zidentyfikowania typów liczbowych i dat.

Jeśli wiersz zawiera mniej lub więcej pól niż pierwszy wiersz w pliku, zostanie zgłoszony wyjątek. Puste wiersze są jednak po prostu ignorowane. Jeśli rozmiar pliku przekracza limit liczby elementów (patrz wewnątrz kodu), pojawia się ostrzeżenie i tablica jest obcinana.

### Składnia:

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

### Parametry:

filename: nazwa pliku tekstowego zawierającego dane. Nazwa musi być wyrażona zgodnie z aktualną właściwością FileNaming usługi SF_FileSystem.

delimiter: pojedynczy znak, zazwyczaj przecinek, średnik lub znak TAB (domyślnie = ",").

dateformat: specjalny mechanizm obsługuje daty, gdy dateformat to "YYYY-MM-DD", "DD-MM-YYYY" lub "MM-DD-YYYY". Dywiz (-) można zastąpić kropką (.), ukośnikiem (/) lub spacją. Inne formaty daty będą ignorowane. Daty z domyślną wartością pustego łańcucha "" są traktowane jako zwykły tekst.

### Przykład:

Rozważ plik CSV "myFile.csv" o następującej zawartości:

Imię,DataUrodzenia,Adres,Miasto

Anna,2002.03.31,"Dworcowa 33", Wrocław

Fryderyk,1998.05.04,"Towarowa 13",Poznań

Poniższe przykłady w językach Basic i Python wczytują zawartość pliku CSV do obiektu Array.

##### W języku Basic

        Dim arr As Variant
        arr = SF_Array.ImportFromCSVFile("C:\Temp\myFile.csv", DateFormat := "YYYY/MM/DD")
        MsgBox arr(0, 3) ' Miasto
        MsgBox arr(1, 2) ' Dworcowa 33
        MsgBox arr(1, 3) ' Wrocław

##### W języku 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]) # Miasto
        bas.MsgBox(arr[1][2]) # Dworcowa 33
        bas.MsgBox(arr[1][3]) # Wrocław

## IndexOf

Poszukaj w jednowymiarowej tablicy liczby, ciągu znaków lub daty. Porównanie tekstu może uwzględniać wielkość liter lub nie.
Jeśli tablica jest posortowana, musi być wypełniona jednorodnie, co oznacza, że wszystkie elementy muszą być skalarami tego samego typu (elementy Empty i Null są zabronione).
Rezultat metody jest nieprzewidywalny, gdy tablica jest ogłaszana jako posortowana, a tak naprawdę nie jest.
Wyszukiwanie binarne jest wykonywane na posortowanych tablicach. W przeciwnym razie tablice są po prostu skanowane od góry do dołu, a elementy Empty i Null są ignorowane.
Metoda zwraca LBound(input array) - 1, jeśli wyszukiwanie nie powiodło się.

### Składnia:

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

### Parametry:

array_1d: tablica do przeskanowania.

tofind: liczba, data lub ciąg znaków do znalezienia.

casesensitive: tylko dla porównań ciągów znaków (domyślnie = False).

sortorder: może to być "ASC", "DESC" lub "" (bez sortowania). Wartość domyślna to "".

### Przykład:

        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

Wstaw przed danym indeksem tablicy wejściowej elementy wymienione jako argumenty.
Argumenty są wstawiane na ślepo. Każdy z nich może być skalarem dowolnego typu lub podtablicą.

### Składnia:

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

### Parametry:

array_1d: istniejąca tablica może być pusta.

before: indeks, przed którym należy wstawić; musi mieścić się w przedziale [LBound, UBound + 1].

arg0, arg1, ...: elementy, które zostaną wstawione do array_1d.

### Przykład:

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

## InsertSorted

Wstawia do posortowanej tablicy nowy element w jego miejsce.
Tablica musi być wypełniona jednorodnie, co oznacza, że wszystkie elementy muszą być skalarami tego samego typu. Elementy
Empty i Null są zabronione.

### Składnia:

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

### Parametry:

array_1d: tablica, do której zostanie wstawiona wartość.

item: wartość skalarna do wstawienia, tego samego typu co istniejące elementy tablicy.

sortorder: może to być "ASC" (domyślnie) lub "DESC".

casesensitive: tylko dla porównań ciągów znaków (domyślnie = False).

### Przykład:

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

## Intersection

Stosuje operator zbioru przecięć do dwóch pól wejściowych, tworząc nowy zbiór w postaci tablicy liczonej od 0. Wynikowe elementy są zawarte w obu tablicach.
Otrzymana tablica jest sortowana w porządku rosnącym.
Obie tablice wejściowe muszą być wypełnione jednorodnie, innymi słowy wszystkie elementy muszą być skalarami tego samego typu. Elementy Empty i Null są zabronione.
Porównanie tekstu może uwzględniać wielkość liter lub nie.

### Składnia:

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

### Parametry:

array1_1d: pierwsza tablica wejściowa.

array2_1d: druga tablica wejściowa.

casesensitive: dotyczy tablic wypełnionych elementami tekstowymi (domyślnie = False).

### Przykład:

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

## Join2D

Połącz dwuwymiarową tablicę z dwoma ogranicznikami, jednym dla kolumn, drugim dla wierszy.

### Składnia:

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

### Parametry:

array_2d: każdy element musi być tekstem, liczbą, datą lub wartością logiczną.
Daty są przekształcane do formatu YYYY-MM-DD hh:mm:ss.
Nieprawidłowe elementy są zastępowane łańcuchem o zerowej długości.

columndelimiter: ogranicza każdą kolumnę (domyślnie = Tab/Chr(9)).

rowdelimiter: ogranicza każdy wiersz (domyślnie = LineFeed/Chr(10))

quote: jeśli True, chroń ciągi za pomocą podwójnych cudzysłowów. Wartość domyślna to False.

### Przykład:

        ' 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

Dołącz na początku tablicy wejściowej elementy wymienione jako argumenty.

### Składnia:

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

### Parametry:

array_1d: istniejąca tablica może być pusta.

arg0, arg1, ...: lista elementów, do których należy dołączyć array_1d.

### Przykład:

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

## PrependColumn

Dodaj nową kolumnę po lewej stronie tablicy dwuwymiarowej. Otrzymana tablica ma takie same dolne granice jak początkowa tablica dwuwymiarowa.

### Składnia:

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

### Parametry:

array_2d: istniejąca tablica może być pusta. Jeśli ta tablica ma 1 wymiar, jest traktowana jako ostatnia kolumna wynikowej tablicy 2-wymiarowej.

column: jednowymiarowa tablica zawierająca tyle elementów, ile jest wierszy w array_2d.

### Przykład:

        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

Dołącz nowy wiersz na początku tablicy 2-wymiarowej. Otrzymana tablica ma takie same dolne granice jak początkowa tablica dwuwymiarowa.

### Składnia:

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

### Parametry:

array_2d: istniejąca wcześniej tablica może być pusta. Jeśli ta tablica ma 1 wymiar, jest traktowana jako pierwszy wiersz wynikowej tablicy dwuwymiarowej.

row: jednowymiarowa tablica zawierająca tyle elementów, ile jest kolumn w array_2d.

### Przykład:

        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

Zainicjuj nową tablicę liczoną od zera z wartościami liczbowymi.

### Składnia:

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

### Parametry:

from: wartość pierwszego elementu.

upto: ostatnia pozycja nie powinna przekraczać UpTo.

bystep: różnica między dwoma kolejnymi elementami (domyślnie = 1).

### Przykład:

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

## Reverse

Zwróć odwróconą jednowymiarową tablicę wejściową.

### Składnia:

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

### Parametry:

array_1d: tablica do odwrócenia.

### Przykład:

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

## Shuffle

Zwraca losową permutację tablicy jednowymiarowej.

### Składnia:

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

### Parametry:

array_1d: tablica do przetasowania.

### Przykład:

        Dim a As Variant
        a = SF_Array.Shuffle(Array(1, 2, 3, 4))
            ' Tablica "a" jest teraz ułożona losowo, np. (2, 3, 1, 4)

## Slice

Zwraca podzbiór tablicy jednowymiarowej.

### Składnia:

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

### Parametry:

array_1d: tablica do podziału.

from: niższy indeks w array_1d podtablicy do wyodrębnienia (w tym from)

upto: górny indeks w array_1d podtablicy do wyodrębnienia (w tym upto). Wartością domyślną jest górna granica array_1d. Jeśli upto < from to zwrócona tablica jest pusta.

### Przykład:

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

## Sort

Sortuj jednowymiarową tablicę w porządku rosnącym lub malejącym. Porównania tekstu mogą uwzględniać wielkość liter lub nie.
Tablica musi być wypełniona jednorodnie, co oznacza, że elementy muszą być skalarami tego samego typu. Dozwolone są elementy
Empty i Null. Konwencjonalnie Empty <Null < dowolna inna wartość skalarna.

### Składnia:

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

### Parametry:

array_1d: tablica do posortowania.

sortorder: może to być "ASC" (domyślnie) lub "DESC".

casesensitive: tylko dla porównań ciągów znaków (domyślnie = False).

### Przykład:

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

## SortColumns

Zwraca permutację kolumn dwuwymiarowej tablicy posortowanej według wartości danego wiersza.
Wiersz musi być wypełniony jednorodnie, co oznacza, że wszystkie elementy muszą być skalarami tego samego typu. Dozwolone są elementy
Empty i Null. Konwencjonalnie Puste <Null < dowolna inna wartość skalarna.

### Składnia:

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

### Parametry:

array_2d: dwuwymiarowa tablica do posortowania.

rowindex: indeks wiersza, który będzie używany jako odniesienie do sortowania kolumn.

sortorder: może to być "ASC" (domyślnie) lub "DESC".

casesensitive: tylko dla porównań ciągów znaków (domyślnie = False).

### Przykład:

        ' 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

Zwraca permutację kolumn dwuwymiarowej tablicy posortowanej według wartości danego wiersza.
Kolumna musi być wypełniona jednorodnie, co oznacza, że wszystkie elementy muszą być skalarami tego samego typu. Dozwolone są elementy
Empty i Null. Konwencjonalnie Puste <Null < dowolna inna wartość skalarna.

### Składnia:

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

### Parametry:

array_2d: tablica do posortowania.

columnindex: indeks kolumny, który będzie używany jako odniesienie do sortowania wierszy.

sortorder: może to być "ASC" (domyślnie) lub "DESC".

casesensitive: tylko dla porównań ciągów znaków (domyślnie = False).

### Przykład:

        ' 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

Zamienia wiersze i kolumny w dwuwymiarowej tablicy.

### Składnia:

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

### Parametry:

array_2d: dwuwymiarowa tablica do transponowania.

### Przykład:

        ' 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

Usuń z jednowymiarowej tablicy wszystkie wpisy Null, Empty i wpisy o zerowej długości.
Elementy łańcuchowe są przycinane za pomocą funkcji LibreOffice Basic Trim().

### Składnia:

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

### Parametry:

array_1d: tablica do przycięcia.

### Przykład:

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

## Union

Stosuje operator union do dwóch pól wejściowych, aby utworzyć zestaw tablic liczonych od 0. Wynikowe elementy mogą pochodzić z obu pól.
Otrzymana tablica jest sortowana w porządku rosnącym.
Oba pola wejściowe muszą być wypełnione jednorodnie, tzn. ich wpisy muszą być skalarami tego samego typu. Wartości Empty i Null są niedozwolone.
Porównania tekstu mogą uwzględniać wielkość liter lub nie.

### Składnia:

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

### Parametry:

array1_1d: pierwsza tablica wejściowa.

array2_1d: druga tablica wejściowa.

casesensitive: ma zastosowanie tylko wtedy, gdy tablice są wypełnione ciągami znaków (domyślnie = False).

### Przykład:

        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

Tworzy zestaw unikalnych wartości z pola wejściowego.
Pole wejściowe musi być wypełnione jednorodnie, tzn. wszystkie elementy muszą być skalarami tego samego typu. Wartości Empty i Null są niedozwolone.
Porównania tekstu mogą uwzględniać wielkość liter lub nie.

### Składnia:

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

### Parametry:

array_1d: tablica wejściowa.

casesensitive: ma zastosowanie tylko wtedy, gdy tablica jest wypełniona ciągami znaków (domyślnie = False).

### Przykład:

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

Wszystkie podstawowe procedury lub identyfikatory ScriptForge poprzedzone znakiem podkreślenia „_” są zarezerwowane do użytku wewnętrznego. Nie należy ich używać w makrach Basic ani skryptach Pythona.

Tematy pokrewne

Funkcje macierzowe

Korzystanie z funkcji Calc w makrach

Usługa ScriptForge.Dictionary

Prosimy o wsparcie!