Služba ScriptForge.Array (SF_Array)

Obsah

# Služba ScriptForge.Array

Poskytuje sadu metod pro manipulaci s jednorozměrnými poli (vektory) a dvourozměrnými poli (maticemi) a jejich transformaci. Mezi ně patří množinové operace, řazení, import z textových souborů a import do nich.

Pole s více než dvěma rozměry nelze pomocí metod této služby používat, jedinou výjimkou je metoda CountDims, která přijímá pole s libovolným počtem rozměrů.

Položky polí mohou obsahovat jakýkoliv typ hodnoty, a to včetně dalších polí.

Jednorozměrná pole obsahující pouze jednorozměrná podpole jsou dále nazývána pole dat. Jsou zvláště vhodné pro výměnu tabulkových dat se skripty v jazyce Python a listy programu Calc.

## Volání služby

Před používáním služby Array je nutné načíst knihovnu ScriptForge pomocí:

        GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

Načtení knihovny vytvoří objekt SF_Array, který lze používat pro volání metod služby Array.

Následující části kódu ukazují různé způsoby volání metod služby Array (jako příklad je uvedena metoda 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)

Protože má Python vestavěnou podporu pro seznam a n-tice, většina metod služby Array je k dispozici pouze pro skripty Basicu. Jedinou výjimku představuje ImportFromCSVFile, která je k dispozici v Basicu i Pythonu.

Seznam metod služby 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

Prvním argumentem většiny metod je objekt pole, s nímž se má pracovat. Vždy je předáván odkazem a metody jej nemění. Metody jako Append, Prepend apod. vracejí po provedení nový objekt pole.

## Append

Přidá položky uvedené jako argumenty na konec vstupního pole.

### Syntaxe:

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

### Parametry:

array_1d: Předem existující pole, může být prázdné.

arg0, arg1, ...:Položky, které se k poli array_1d přidají.

### Příklad:

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

## AppendColumn

Přidá na pravou stranu dvourozměrného pole nový sloupec. Výsledné pole má stejné dolní meze jako původní dvourozměrné pole.

### Syntaxe:

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

### Parametry:

array_2d: Předem existující pole, může být prázdné. Pokud je toto pole pouze jednorozměrné, je považováno za první sloupec výsledného dvourozměrného pole.

column: Jednorozměrné pole s tolika položkami, kolik má pole array_2d řádků.

### Příklad:

        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

Přidá do dolní části dvourozměrného pole nový řádek. Výsledné pole má stejné dolní meze jako původní dvourozměrné pole.

### Syntaxe:

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

### Parametry:

array_2d: Předem existující pole, může být prázdné. Pokud je toto pole pouze jednorozměrné, je považováno za první řádek výsledného dvourozměrného pole.

row: Jednorozměrné pole s tolika položkami, kolik má pole array_2d sloupců.

### Příklad:

        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

Ověří, zda jednorozměrné pole obsahuje určité číslo, text nebo datum. U porovnání textu se může či nemusí rozlišovat velikost písmen.
Seřazená vstupní pole musí být homogenně vyplněna, tj. všechny položky musí být skaláry téhož typu (položky Empty a Null nejsou povoleny).
Výsledek metody nelze určit, pokud je pole označeno jako seřazené, ale ve skutečnosti seřazeno není.
Je-li pole seřazeno, provede se binární vyhledávání, v opačném případě se pole prohledá od začátku do konce, přičemž položky Empty a Null se ignorují.

### Syntaxe:

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

### Parametry:

array_1d: Pole, které se má prohledat.

tofind: Číslo, datum nebo řetězec, který se má najít.

casesensitive: Pouze pro porovnání řetězců (výchozí = False).

sortorder: Může být jedna z hodnot "ASC", "DESC" nebo "" (neseřazeno). Výchozí hodnotou je "".

### Příklad:

        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

Převede pole dat na pole jazyka Basic.
Pole dat je pole podpolí. Na požádání jsou jednotlivé položky výstupu redukovány na řetězce nebo čísla typu double.

Metoda vrací skalár, jednorozměrné pole začínající od 0 nebo dvourozměrné pole začínající od 0.
Počet sloupců ve výsledném dvourozměrném poli se rovná počtu položek v prvním podpoli. Pokud mají další podpole jinou velikost, jejich řádky budou doplněny argumentem fillvalue nebo budou zkráceny.

### Syntaxe:

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

### Parametry:

dataarray: Pole skládající se z podpolí. Pole a podpole musí začínat nulou.
Typicky je pole dat výstupem

- metody session.ExecuteCalcFunction()

- skriptu Pythonu vracejícího n-tici n-tic

- metody getDataArray() z rozhraní com.sun.star.sheet.XCellRangeData

isrange: Je-li True (výchozí = False), položky se převedou na řetězce, nebo čísla typu double.

fillvalue: Čím nahradit chybějící položky. Výchozí = prázdný řetězec.

### Příklad:

        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

Vytvoří pole dat ze skaláru, jednorozměrného pole nebo dvourozměrného pole.
Pole dat se skládá z podpolí, pole i podpole začínají od 0. Na požádání jsou jednotlivé položky výstup redukovány na řetězce nebo čísla typu double.

Vrácené pole dat se typicky používá jako

- n-tice (pod)n-tic předávaných skriptu Pythonu

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

### Syntaxe:

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

### Parametry:

data: Vstupní skalár nebo jednorozměrné či dvourozměrné pole.

isrange: Je-li True (výchozí = False), položky pole se uloží do pole dat jako řetězce (mohou být i prázdné), nebo čísla typu double.

rows, columns: Počet řádků nebo sloupců vráceného pole dat. Položky přesahující rozměry argumentu data se vyplní řetezci nulové délky. Pokud rows = 1 a vstupním polem je vektor, pole dat bude uspořádáno vodorovně (ve výchozím nastavení jsou vektory uspořádány svisle). Není-li zadáno, velikost výstupu se určí podle vstupního pole.

### Příklad:

        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

Uloží obsah dvourozměrného pole do objektu ScriptForge.Dictionary.
Klíče budou získány z prvního sloupce, položky z druhého.

### Syntaxe:

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

### Parametry:

array_2d: Data, která se mají převést na objekt ScriptForge.Dictionary.

- První sloupec musí obsahovat výhradně řetězce s délkou větší než nula, a to v jakémkoliv pořadí. Tyto hodnoty se použijí jako klíče slovníku.

- Druhý sloupec obsahuje data, která budou k odpovídajícímu klíči slovníku přiřazena.

### Příklad:

        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

Vytvoří platný obsah oblasti buněk ze skaláru, jednorozměrného či dvourozměrného pole nebo pole dat (pole dat je od 0 začínající pole od 0 začínajících podpolí). Ve výstupu se zachovají dolní meze polí.

Jednotlivé položky se vždy redukují na řetězce nebo čísla typu double, a to včetně booleovských hodnot nebo dat.

Vrácený skalár nebo dvourozměrné pole je platným argumentem metody session.ExecuteCalcFunction(). To je užitečné zejména při práci s komplexními maticovými funkcemi.

### Syntaxe:

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

### Parametry:

data: Vstupní skalár, jednorozměrné či dvourozměrné pole nebo pole dat.

direction: Uspořádání oblasti, pokud se jedná o vektor, buď "V" (svislé), nebo "H" (vodorovné).

### Příklad:

        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

Vytvoří kopii jednorozměrného či dvourozměrného pole.

### Syntaxe:

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

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

### Parametry:

array_nd: Jednorozměrné či dvourozměrné pole, které se má zkopírovat.

### Příklad:

Prosté přiřazení objektu Array zkopíruje odkaz na objekt místo vytvoření kopie jeho obsahu. Viz následující příklad:

        Dim a as Variant, b as Variant
        a = Array(1, 2, 3)
        ' Přiřazení níže je odkazem
        b = a
        ' Proto se při změně hodnot v "b" změní také "a"
        b(0) = 10
        MsgBox a(0) ' 10

Při použití metody Copy se vytvoří kopie celého objektu Array. V následujícím příkladu jsou a a b rozdílné objekty a změny hodnot v b nijak neovlivní hodnoty v a.

        Dim a as Variant, b as Variant
        a = Array(1, 2, 3)
        ' Vytvoří kopii "a" pomocí metody "Copy"
        b = SF_Array.Copy(a)
        b(0) = 10
        MsgBox a(0) ' 1

## CountDims

Spočítá rozměry pole. Výsledek může být větší než 2.
Pokud není argumentem pole, vrátí -1.
Pokud není pole inicializováno, vrátí 0.

### Syntaxe:

svc.CountDims(array_nd: any): int

### Parametry:

array_nd: Pole, které se má prozkoumat.

### Příklad:

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

## Difference

Použije operátor rozdílu na dvě vstupní pole a vytvoří tak množinu v podobě pole začínajícího od 0. Výsledné položky pocházejí z prvního pole, nikoliv ze druhého.
Výsledné pole je vzestupně seřazeno.
Obě vstupní pole musí být homogenně vyplněna, tj. jejich položky musí být skaláry téhož typu. Položky Empty a Null nejsou povoleny.
Porovnání textu může či nemusí rozlišovat velikost písmen.

### Syntaxe:

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

### Parametry:

array1_1d: Referenční jednorozměrné pole, pro jehož položky se bude zjišťovat, zda mají být odstraněny.

array2_1d: Jednorozměrné pole, jehož položky se od prvního vstupního pole odčítají.

casesensitive: Tento argument je použitelný pouze tehdy, obsahují-li pole řetězce (výchozí = False).

### Příklad:

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

## ExportToTextFile

Postupně zapíše všechny položky pole do textového souboru. Pokud již soubor existuje, bez upozornění je přepsán.

### Syntaxe:

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

### Parametry:

array_1d: Pole, které se má exportovat. Může obsahovat pouze řetězce.

filename: Název textového souboru, do něhož se mají data zapsat. Název musí odpovídat aktuální vlastnosti FileNaming ze služby SF_FileSystem.

encoding: Znaková sada, která by se měla použít. Uveďte některý z názvů ze seznamu znakových sad IANA. Mějte na paměti, že v LibreOffice nemusí být všechny znakové sady implementovány. (Výchozí je "UTF-8".)

### Příklad:

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

## ExtractColumn

Získá z dvourozměrného pole určitý sloupec jako nové pole.
Meze nového pole, dolní LBound a horní UBound, jsou totožné s mezemi prvního rozměru vstupního pole.

### Syntaxe:

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

### Parametry:

array_2d: Pole, z něhož se má sloupec získat.

columnindex: Číslo sloupce, který se má získat. Musí být v intervalu [LBound, UBound].

### Příklad:

        ' Vytvoří matici 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))
        ' Získá třetí sloupec: [3, 6, 9]
        col = SF_Array.ExtractColumn(mat, 2)

## ExtractRow

Získá z dvourozměrného pole určitý řádek jako nové pole.
Meze nového pole, dolní LBound a horní UBound, jsou totožné s mezemi druhého rozměru vstupního pole.

### Syntaxe:

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

### Parametry:

array_2d: Pole, z něhož se má řádek získat.

rowindex: Číslo řádku, který se má získat. Musí být v intervalu [LBound, UBound].

### Příklad:

        ' Vytvoří matici 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))
        ' Získá první řádek: |1, 2, 3|
        row = SF_Array.ExtractRow(mat, 0)

## Flatten

Uspořádá všechny jednotlivé položky pole a položky všech jeho podpolí do nového pole, které podpole neobsahuje. Prázdná podpole se ignorují, podpole s více rozměry než jedním zjednodušena nejsou.

### Syntaxe:

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

### Parametry:

array_1d: Předem existující pole, může být prázdné.

### Příklad:

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

Metodu Flatten je možné spolu s metodami jako Append či Prepend použít pro spojení více jednorozměrných polí do jediného jednorozměrného pole.

### Příklad:

Následuje příklad spojení tří polí zkombinováním metod Flatten a Append.

        ' Vytvoří pro tento příklad tři pole
        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)
        ' Spojí tři pole do jediného jednorozměrného
        Dim arr as Variant
        arr = SF_Array.Flatten(SF_Array.Append(a, b, c))
        '(1, 2, 3, 4, 5, 6, 7, 8, 9)

## ImportFromCSVFile

Naimportuje data ze souboru s hodnotami oddělenými čárkou (CSV). Čárku lze nahradit libovolným znakem.

Formát CSV, který je možné použít, je popsán v dookumentu IETF Common Format and MIME Type for CSV Files.

Každý řádek souboru obsahuje úplný záznam (není povoleno řádky dělit).
Posloupnosti znaků jako \n, \t apod. jsou ponechány beze změny. Chcete-li je zpracovat, použijte metodu SF_String.Unescape().

Metoda vrátí dvourozměrné pole s řádky odpovídajícími záznamům načteným ze souboru a sloupci odpovídajícími jednotlivým polím záznamů. Nekontroluje se, zda jsou ve sloupcích konzistentní typy polí. Kvalifikovaným odhadem se určí číselné a datové typy.

Obsahuje-li řádek více polí než první řádek v souboru, nastane chyba. Prázdné řádky se jednoduše ignorují. Pokud velikost souboru převýší limit pro počet položek (uvedený v kódu), dojde k upozornění a pole se zkrátí.

### Syntaxe:

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

### Parametry:

filename: Název textového souboru obsahujícího data. Název musí odpovídat aktuální vlastnosti FileNaming ze služby SF_FileSystem.

delimiter: Jediný znak, obvykle čárka, středník nebo tabulátor (výchozí = ",").

dateformat: Pokud je dateformat "YYYY-MM-DD", "DD-MM-YYYY" či "MM-DD-YYYY", zpracují se data speciálním způsobem. Pomlčku (-) lze nahradit tečkou (.), lomítkem (/) nebo mezerou. Jiné formáty data se ignorují. Data, která odpovídají prázdnému řetězci "", jsou považována za běžný text.

### Příklad:

Soubor CSV "myFile.csv" obsahuje následující řádky:

Jméno,DatumNarození,Adresa,Město

Anna,31.03.2002,"Anenské údolí 15",Rotava

Franta,04.05.1998,"Francouzská 35",Františkovy Lázně

Následující příklady načtou obsah souboru CSV do objektu Array v jazycích Basic a Python.

##### V Basicu

        Dim arr As Variant
        arr = SF_Array.ImportFromCSVFile("C:\Temp\myFile.csv", DateFormat := "DD.MM.YYYY")
        MsgBox arr(0, 3) ' Město
        MsgBox arr(1, 2) ' Anenské údolí 15
        MsgBox arr(1, 3) ' Rotava

##### V Pythonu

        from scriptforge import CreateScriptService
        svc = CreateScriptService("Array")
        bas = CreateScriptService("Basic")
        arr = svc.ImportFromCSVFile("C:\Temp\myFile.csv", DateFormat := "DD.MM.YYYY")
        bas.MsgBox(arr[0][3]) # Město
        bas.MsgBox(arr[1][2]) # Anenské údolí 15
        bas.MsgBox(arr[1][3]) # Rotava

## IndexOf

Vyhledá v jednorozměrném poli číslo, řetězec nebo datum. U porovnání textu se může či nemusí rozlišovat velikost písmen.
Seřazená vstupní pole musí být homogenně vyplněna, tj. všechny položky musí být skaláry téhož typu (položky Empty a Null nejsou povoleny).
Výsledek metody nelze určit, pokud je pole označeno jako seřazené, ale ve skutečnosti seřazeno není.
Je-li pole seřazeno, provede se binární vyhledávání, v opačném případě se pole prohledá od začátku do konce, přičemž položky Empty a Null se ignorují.
Pokud není hledání úspěšné, metoda vrátí LBound(input array) - 1.

### Syntaxe:

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

### Parametry:

array_1d: Pole, které se má prohledat.

tofind: Číslo, datum nebo řetězec, který se má najít.

casesensitive: Pouze pro porovnání řetězců (výchozí = False).

sortorder: Může být jedna z hodnot "ASC", "DESC" nebo "" (neseřazeno). Výchozí hodnotou je "".

### Příklad:

        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

Vloží před zadaný index vstupního pole položky uvedené jako argumenty.
Argumenty se vkládají bez jakékoliv kontroly. Každý z nich může být buď skalár libovolného typu, nebo podpole.

### Syntaxe:

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

### Parametry:

array_1d: Předem existující pole, může být prázdné.

before: Index, před který se položky vloží; musí být v intervalu [LBound, UBound + 1].

arg0, arg1, ...: Položky, které se do pole array_1d vloží.

### Příklad:

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

## InsertSorted

Vloží do seřazeného pole na správné místo novou položku.
Seřazená vstupní pole musí být homogenně vyplněna, tj. všechny položky musí být skaláry téhož typu.
Položky Empty a Null nejsou povoleny.

### Syntaxe:

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

### Parametry:

array_1d: Pole, do něhož se hodnota vloží.

item: Skalární hodnota, která se má vložit, téhož typu jako stávající položky pole.

sortorder: Může být "ASC" (výchozí) nebo "DESC".

casesensitive: Pouze pro porovnání řetězců (výchozí = False).

### Příklad:

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

## Intersection

Použije na dvě vstupní pole množinový operátor průniku a vytvoří tak novou množinu v podobě pole začínajícího od 0. Výsledné položky jsou obsaženy v obou polích.
Výsledné pole je vzestupně seřazeno.
Obě vstupní pole musí být homogenně vyplněna, tj. jejich položky musí být skaláry téhož typu. Položky Empty a Null nejsou povoleny.
Porovnání textu může či nemusí rozlišovat velikost písmen.

### Syntaxe:

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

### Parametry:

array1_1d: První vstupní pole.

array2_1d: Druhé vstupní pole.

casesensitive: Týká se polí s textovými položkami (výchozí = False).

### Příklad:

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

## Join2D

Spojí položky dvourozměrného pole dvěma oddělovači, prvním mezi sloupci, druhým mezi řádky.

### Syntaxe:

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

### Parametry:

array_2d: Každá položka musí být text, číslo, datum nebo booleovská hodnota.
Data jsou převedena na formát YYYY-MM-DD hh:mm:ss.
Neplatné položky jsou nahrazeny řetězci s nulovou délkou.

columndelimiter: Odděluje sloupce (výchozí = tabulátor/Chr(9)).

rowdelimiter: Odděluje řádky (výchozí = konec řádku LF / Chr(10))

quote: Je-li True, uzavře řetězce do dvojitých uvozovek. Výchozí je False.

### Příklad:

        ' 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

Přidá položky uvedené jako argumenty na začátek vstupního pole.

### Syntaxe:

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

### Parametry:

array_1d: Předem existující pole, může být prázdné.

arg0, arg1, ...: Seznam položek, které se mají k poli array_1d přidat.

### Příklad:

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

## PrependColumn

Přidá na levou stranu dvourozměrného pole nový sloupec. Výsledné pole má stejné dolní meze jako původní dvourozměrné pole.

### Syntaxe:

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

### Parametry:

array_2d: Předem existující pole, může být prázdné. Pokud je toto pole pouze jednorozměrné, je považováno za poslední řádek výsledného dvourozměrného pole.

column: Jednorozměrné pole s tolika položkami, kolik má pole array_2d řádků.

### Příklad:

        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

Přidá na začátek dvourozměrného pole nový řádek. Výsledné pole má stejné dolní meze jako původní dvourozměrné pole.

### Syntaxe:

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

### Parametry:

array_2d: Předem existující pole, může být prázdné. Pokud je toto pole pouze jednorozměrné, je považováno za poslední řádek výsledného dvourozměrného pole.

row: Jednorozměrné pole s tolika položkami, kolik má pole array_2d sloupců.

### Příklad:

        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

Inicializuje číselnými hodnotami nové pole začínající od 0.

### Syntaxe:

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

### Parametry:

from: Hodnota první položky.

upto: Poslední položka by neměla být větší než UpTo.

bystep: Rozdíl mezi dvěma po sobě následujícími položkami (výchozí = 1).

### Příklad:

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

## Reverse

Vrátí obrácené jednorozměrné vstupní pole.

### Syntaxe:

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

### Parametry:

array_1d: Pole, které se má obrátit.

### Příklad:

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

## Shuffle

Vrátí náhodnou permutaci jednorozměrného pole.

### Syntaxe:

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

### Parametry:

array_1d: Pole, jehož permutace se má vytvořit.

### Příklad:

        Dim a As Variant
        a = SF_Array.Shuffle(Array(1, 2, 3, 4))
            ' Array "a" je v náhodném pořadí, např. (2, 3, 1, 4)

## Slice

Vrátí podmnožinu jednorozměrného pole.

### Syntaxe:

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

### Parametry:

array_1d: Pole, jehož podmnožina se má vrátit.

from: Dolní index pole array_1d, od něhož se má podpole získat (včetně indexu from)

upto: Horní index pole array_1d, do něhož se má podpole získat (včetně indexu upto). Výchozí hodnotou je horní mez pole array_1d. Je-li upto < from, vrátí se prázdné pole.

### Příklad:

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

## Sort

Seřadí jednorozměrné pole vzestupně nebo sestupně. Při porovnávání textů se může či nemusí rozlišovat velikost písmen.
Pole musí být homogenně vyplněno, tj. všechny položky musí být skaláry téhož typu.
Položky Empty a Null jsou povoleny. Platí, že Empty < Null < jakákoliv jiná skalární hodnota.

### Syntaxe:

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

### Parametry:

array_1d: Pole, které se má seřadit.

sortorder: Může být "ASC" (výchozí) nebo "DESC".

casesensitive: Pouze pro porovnání řetězců (výchozí = False).

### Příklad:

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

## SortColumns

Vrátí permutaci sloupců dvourozměrného pole, seřazenou podle hodnot v zadaném řádku.
Pole musí být homogenně vyplněno, tj. všechny položky musí být skaláry téhož typu.
Položky Empty a Null jsou povoleny. Platí, že Empty < Null < jakákoliv jiná skalární hodnota.

### Syntaxe:

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

### Parametry:

array_2d: Dvourozměrné pole, které se má seřadit.

rowindex: Index řádku, který bude pro řazení sloupců použit.

sortorder: Může být "ASC" (výchozí) nebo "DESC".

casesensitive: Pouze pro porovnání řetězců (výchozí = False).

### Příklad:

        ' 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

Vrátí permutaci řádků dvourozměrného pole, seřazenou podle hodnot v zadaném sloupci.
Pole musí být homogenně vyplněno, tj. všechny položky musí být skaláry téhož typu.
Položky Empty a Null jsou povoleny. Platí, že Empty < Null < jakákoliv jiná skalární hodnota.

### Syntaxe:

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

### Parametry:

array_2d: Pole, které se má seřadit.

columnindex: Index sloupce, který bude pro řazení řádků použit.

sortorder: Může být "ASC" (výchozí) nebo "DESC".

casesensitive: Pouze pro porovnání řetězců (výchozí = False).

### Příklad:

        ' 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

Prohodí v dvourozměrném poli řádky a sloupce.

### Syntaxe:

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

### Parametry:

array_2d: Dvourozměrné pole, které se má transponovat.

### Příklad:

        ' 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

Odstraní z jednorozměrného pole všechny položky s nulovou délkou a s hodnotami Null, Empty.
Řetězce v položkách budou oříznuty funkcí LibreOffice Basic Trim().

### Syntaxe:

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

### Parametry:

array_1d: Pole, které se má oříznout.

### Příklad:

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

## Union

Použije operátor sjednocení na dvě vstupní pole a vytvoří tak množinu v podobě pole začínajícího od 0. Výsledné položky mohou pocházet z obou polí.
Výsledné pole je vzestupně seřazeno.
Obě vstupní pole musí být homogenně vyplněna, tj. jejich položky musí být skaláry téhož typu. Položky Empty a Null nejsou povoleny.
Porovnání textu může či nemusí rozlišovat velikost písmen.

### Syntaxe:

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

### Parametry:

array1_1d: První vstupní pole.

array2_1d: Druhé vstupní pole.

casesensitive: Použitelné pouze tehdy, obsahují-li pole řetězce (výchozí = False).

### Příklad:

        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

Vytvoří ze vstupního pole množinu jedinečných hodnot.
Vstupní pole musí být homogenně vyplněno, tj. všechny položky musí být skaláry téhož typu. Položky Empty a Null nejsou povoleny.
Porovnání textu může či nemusí rozlišovat velikost písmen.

### Syntaxe:

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

### Parametry:

array_1d: Vstupní pole.

casesensitive: Použitelné pouze tehdy, obsahuje-li pole řetězce (výchozí = False).

### Příklad:

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

Všechny procedury nebo identifikátory knihovny ScriptForge, které jsou uvozeny podtržítkem "_", jsou určeny pro interní použití. Není zamýšleno je používat v makrech Basicu nebo skriptech Pythonu.

Související témata

Maticové funkce

Použití funkcí Calcu v makrech

Služba ScriptForge.Dictionary

Podpořte nás!