Obsah

# Služba ScriptForge.Region

Služba Region nabízí sadu vlastností a metod pro práci s národním prostředím a dalšími částmi programování souvisejícími s regionem, například:

- Přístup k národnímu prostředí a nastavením závisejícím na regionu, jako jsou formátování čísel, měna a časová pásma.

- Převod mezi časovými pásmy a výpočet posunů pro letní čas.

- Převod čísel na text v podporovaných jazycích.

## Definice

### Národní prostředí nebo region

Řetězec s kombinací jazyka a země ve tvaru „la-CO“. Část s jazykem, vyjádřeným 2 nebo 3 malými písmeny, následuje pomlčka a 2 velká písmena představující zemi.

Například „en-US“ odpovídá angličtině ve Spojených státech, „fr-BE“ francouzštině v Belgii, „cs-CZ“ češtině v České republice atd.

V některých případech není úplné označení národního prostředí vyžadováno a stačí určit pouze jazyk či zemi.

Většina vlastností a metoda má národní prostředí jako argument. Není-li žádné uvedeno, použije se národní prostředí uživatelského rozhraní, které je definováno ve vlastnosti OfficeLocale služby Platform.

### Časové pásmo

Řetězec ve formátu „Region/město“, například „Europe/Prague“, nebo identifikátor časového pásma, například „UTC“ nebo „GMT-8:00“. Seznam názvů a identifikátorů časových pásem naleznete na wiki stránce List of tz database and timezones.

Bude-li jakékoliv metodě služby Region zadáno neplatná neplatné časové pásmo, nenastane chyba při běhu programu. Místo toho se pomocí metod jako UTCDateTime a UTCNow vrátí aktuální datum a čas z operačního systému.

Posun času mezi časovým pásmem a greenwichským středním časem (Greenwich Meridian Time, GMT) je vyjádřen v minutách.

Dodatečný posun způsobuje letní čas (Daylight Saving Time, DST).

Posun časového pásma a posun pro letní čas mohou být kladné, nebo záporné.

## Volání služby

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

• V makrech Basicu je nutné načíst knihovnu ScriptForge následujícím příkazem:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Ve skriptech Pythonu je nezbytné import z modulu scriptforge:
from scriptforge import CreateScriptService

V níže uvedených příkladech v Basicu a Pythonu je vytvořena instance služby Region a je získán přístup k vlastnosti Country.

##### V Basicu

        GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
        Dim oRegion As Variant
        oRegion = CreateScriptService("Region")
        MsgBox oRegion.Country("en-US") ' United States

##### V Pythonu

        from scriptforge import CreateScriptService
        oRregion = CreateScriptService("Region")
        bas = CreateScriptService("Basic")
        bas.MsgBox(oRegion.Country("en-US"))

## Vlastnosti

Všechny následující vlastnosti přijímají argument locale, zadaný jako řetězec. Některý vyžadují, aby byl ve formátu „la-CO“, jiným je možné předat jako vstup formát „la“ nebo „CO“.

Název | Pouze pro čtení | Typ | Národní prostředí | Popis
--- | --- | --- | --- | ---
Country | ano | String | "la‑CO" "CO" | Vrátí v angličtině název země odpovídající zadanému regionu.
Currency | ano | String | "la-CO" "CO" | Vrátí pro zadaný region kód měny podle normy ISO 4217.
DatePatterns | ano | pole řetězců (String) | "la-CO" | Vrátí pole řetězců začínající od 0, které obsahuje pro zadaný region masky pro rozpoznání data.
DateSeparator | ano | String | "la-CO" | Vrátí oddělovač data používaný v zadaném regionu.
DayAbbrevNames | ano | pole řetězců (String) | "la-CO" "la" | Vrátí pole řetězců začínající od 0, které obsahuje seznam zkratek dnů v zadaném jazyce.
DayNames | ano | pole řetězců (String) | "la-CO" "la" | Vrátí pole řetězců začínající od 0, které obsahuje seznam názvů dnů v zadaném jazyce.
DayNarrowNames | ano | pole řetězců (String) | "la-CO" "la" | Vrátí pole řetězců začínající od 0, které obsahuje seznam počátečních písmen dnů v zadaném jazyce.
DecimalPoint | ano | String | "la-CO" | Vrátí desetinný oddělovač používaný u čísel v zadaném regionu.
Language | ano | String | "la-CO" "la" | Vrátí v angličtině název jazyka pro zadaný region.
ListSeparator | ano | String | "la-CO" | Vrátí oddělovač seznamu používaný v zadaném regionu.
MonthAbbrevNames | ano | pole řetězců (String) | "la-CO" "la" | Vrátí pole řetězců začínající od 0, které obsahuje seznam zkratek měsíců v zadaném jazyce.
MonthNames | ano | pole řetězců (String) | "la-CO" "la" | Vrátí pole řetězců začínající od 0, které obsahuje seznam názvů měsíců v zadaném jazyce.
MonthNarrowNames | ano | pole řetězců (String) | "la-CO" "la" | Vrátí pole řetězců začínající od 0, které obsahuje seznam počátečních písmen měsíců v zadaném jazyce.
ThousandSeparator | ano | String | "la-CO" | Vrátí oddělovač tisíců používaný u čísel v zadaném regionu.
TimeSeparator | ano | String | "la-CO" | Vrátí oddělovač seznamu používaný v zadaném regionu pro formátování časů.

Seznam metod služby Region
DSTOffset LocalDateTime | Number2Text TimeZoneOffset | UTCDateTime UTCNow

## DSTOffset

Vypočítá dodatečný posun pro letní čas (DST) v minutách, který odpovídá zadanému regionu a časovému pásmu.

### Syntaxe:

svc.DSTOffset(localdatetime: date, timezone: str, opt locale: str): int

### Parametry:

localdatetime: místní datum a čas vyjádřené jako datum.

timezone: časová zóna, pro niž se posun vypočítá.

locale: národní prostředí určující zemi, pro niž se má posun vypočítat, ve formátu „la-CO“ nebo „CO“. Výchozí hodnotou je národní prostředí definované ve vlastnosti OfficeLocale služby Platform.

### Příklad:

##### V Basicu

          ' Vypočítá posun pro časové pásmo "America/Los_Angeles"
          Dim aDateTime As Date, offset As Integer
          aDateTime = DateSerial(2022, 7, 1) + TimeSerial(16, 0, 0)
          offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 60 (minut)
          aDateTime = DateSerial(2022, 1, 1) + TimeSerial(16, 0, 0)
          offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 0 (minut)

##### V Pythonu

          import datetime
          aDateTime = datetime.datetime(2022, 7, 1, 16, 0, 0)
          offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 60 (minut
    )
          aDateTime = datetime.datetime(2022, 1, 1, 16, 0, 0)
          offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 0 (minut)

## LocalDateTime

Vypočítá místní datum a čas z data a času v UTC.

### Syntaxe:

svc.LocalDateTime(utcdatetime: date, timezone: str, opt locale: str): date

### Parametry:

utcdatetime: datum a čas v UTC vyjádřený pomocí objektu s datem.

timezone: časová zóna, pro niž se místní čas vypočítá.

locale: národní prostředí určující zemi, pro niž se má místní čas vypočítat, ve formátu „la-CO“ nebo „CO“. Výchozí hodnotou je národní prostředí definované ve vlastnosti OfficeLocale služby Platform.

### Příklad:

##### V Basicu

          ' 6. června 2022 v 10:30:45 (použito jako čas UTC)
          Dim UTCTime As Date, localTime As Date
          UTCTime = DateSerial(2022, 6, 23) + TimeSerial(10, 30, 45)
          ' Vypočítá místní čas v brazilském městě Sao Paulo
          ' 6. června 2022 v 7:30:45
          localTime = oRegion.LocalDateTime(UTCTime, "America/Sao_Paulo", "BR")

##### V Pythonu

          import datetime
          utcTime = datetime.datetime(2022, 6, 23, 10, 30, 45)
          localTime = oRegion.LocalDateTime(utcTime, "America/Sao_Paulo", "BR")

## Number2Text

Převede pro aktuálně podporované jazyky čísla a hodnoty měny na psaný text.

Seznam všech podporovaných jazyků naleznete v části XNumberText Interface v referenční příručce API.

### Syntaxe:

svc.Number2Text(number: any, opt locale: str): str

### Parametry:

number: číslo, které se má převést na psaný text. Může být zadáno jako číselný typ nebo jako řetězec. Je-li zadán řetězec, lze u něj uvést předponu, která značí, jak mají být čísla zapsána. Je také možné použít kódy měn podle normy ISO 4217. Další informace naleznete v příkladech.

locale: národní prostředí určující jazyk, v němž bude převedené číslo zapsáno, ve formátu „la-CO“ nebo „CO“. Výchozí hodnotou je národní prostředí definované ve vlastnosti OfficeLocale služby Platform.

### Příklad:

##### V Basicu

          ' Vrátí "sto pět"
          Dim numText As String
          numText = oRegion.Number2Text(105, "cs-CZ")
          ' Vrátí: "dvě čárka čtyřicet dva"
          numText = oRegion.Number2Text(2.42, "cs-CZ")
          ' Vrátí: "dvacet pět korun českých 10 haléřů" (použit symbol měny "CZK")
          numText = oRegion.Number2Text("CZK 25.10", "cs-CZ")
          ' Vrátí: "patnáctý" (použita předpona "ordinal" pro řadové číslovky)
          numText = oRegion.Number2Text("ordinal 15", "cs-CZ")

##### V Pythonu

          numText = oRegion.Number2Text(105, "cs-CZ")
          numText = oRegion.Number2Text(2.42, "cs-CZ")
          numText = oRegion.Number2Text("EUR 25.10", "cs-CZ")
          numText = oRegion.Number2Text("ordinal 15", "cs-CZ")

Seznam všech podporovaných předpon pro daný jazyk získáte zavoláním Number2Text se speciálním argumentem "help". Následující příklad předpokládá národní prostředí nastavené na "en-US", pro které se v okně MsgBox proto zobrazí seznam dostupných předpon:

          prefixes = oRegion.Number2Text("help")
          MsgBox prefixes
          ' one, two, three
          ' ordinal: first, second, third
          ' ordinal-number: 1st, 2nd, 3rd
          ' year: nineteen ninety-nine, two thousand, two thousand one
          ' currency (for example, USD): two U.S. dollars and fifty cents
          ' money USD: two and 50/100 U.S. dollars

První řádek v dialogu je bez předpony a značí standardní formát. Na následujících řádcích jsou uvedeny předpony a několik příkladů odpovídajících číslovek.

Každý jazyk má vlastní sadu podporovaných předpon, jejich počet se může v závislosti na jazyku lišit.

Seznam všech podporovaných předpon pro daný jazyk nebo národní prostředí získáte zavoláním Number2Text s druhým argumentem. Následující příklad zobrazí předpony dostupné pro prostředí "pt-BR":

          prefixes = oRegion.Number2Text("help", "pt-BR")
          MsgBox prefixes
          ' um, dois, três
          ' feminine: uma, duas, três
          ' masculine: um, dois, três
          ' ordinal-feminine: primeira, segunda, terceira
          ' ordinal-masculine: primeiro, segundo, terceiro
          ' ordinal-number-feminine: 1.ª, 2.ª, 3.ª
          ' ordinal-number-masculine: 1.º, 2.º, 3.º

## TimeZoneOffset

Vrátí v minutách posun mezi GMT a zadaným časovým pásmem a národním prostředím.

### Syntaxe:

svc.TimeZoneOffset(timezone: str, opt locale: str): int

### Parametry:

timezone: časová zóna, pro niž se posun vzhledem k GMT vypočítá.

locale: národní prostředí určující zemi, pro niž se má posun vypočítat, ve formátu „la-CO“ nebo „CO“. Výchozí hodnotou je národní prostředí definované ve vlastnosti OfficeLocale služby Platform.

### Příklad:

##### V Basicu

          Dim offset As Integer
          offset = oRegion.TimeZoneOffset("America/New_York", "US") ' -300
          offset = oRegion.TimeZoneOffset("Europe/Berlin", "DE") ' 60

##### V Pythonu

          offset = oRegion.TimeZoneOffset("America/New_York", "US") # -300
          offset = oRegion.TimeZoneOffset("Europe/Berlin", "DE") # 60

## UTCDateTime

Vrátí datum a čas v UTC pro zadané místní datum a čas v určitém časovém pásmu.

### Syntaxe:

svc.UTCDateTime(localdatetime: date, timezone: str, opt locale: str): date

### Parametry:

localdatetime: místní datum a čas v určitém časovém pásmu vyjádřené jako datum.

timezone: časové pásmo, pro nějž byl zadán argument localdatetime.

locale: národní prostředí určující zemi, pro niž byl zadán argument localdatetime, ve formátu „la-CO“ nebo „CO“. Výchozí hodnotou je národní prostředí definované ve vlastnosti OfficeLocale služby Platform.

### Příklad:

##### V Basicu

          ' Datum a čas v Praze je 23. června 2022 14:30:00
          Dim localDT As Date, utcTime As Date
          localDT = DateSerial(2022, 6, 23) + TimeSerial(14, 30, 0)
          ' Datum a čas v UTC je 23. června 2022 12:30:00
          utcTime = oRegion.UTCDateTime(localDT, "Europe/Berlin", "DE")

##### V Pythonu

          import datetime
          localDT = datetime.datetime(2022, 6, 23, 14, 30, 0)
          utcTime = oRegion.UTCDateTime(localDT, "Europe/Berlin", "DE")

## UTCNow

Vrátí aktuální datum a čas UTC pro zadané časové pásmo a národní prostředí.

Pro výpočet času UTC používá tato metoda aktuální datum a čas operačního systému.

### Syntaxe:

svc.UTCNow(timezone: str, opt locale: str): date

### Parametry:

timezone: časová zóna, pro niž se aktuální čas UTC vypočítá.

locale: národní prostředí určující zemi, pro niž se má čas UTC vypočítat, ve formátu „la-CO“ nebo „CO“. Výchozí hodnotou je národní prostředí definované ve vlastnosti OfficeLocale služby Platform.

### Příklad:

##### V Basicu

          ' Předpokládejme, že čas operačního systému je 23. června 2022 10:42:00
          ' Nachází-li se počítač v pásmu Europe/Prague, je čas UTC 23. června 2022 8:42:00
          Dim utcTime As Date
          utcTime = oRegion.UTCNow("Europe/Berlin", "DE")

##### V Pythonu

          utcTime = oRegion.UTCNow("Europe/Prague", "CZ")

Související témata

Služba ScriptForge.Platform