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.

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

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

DSTOffset

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

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

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.

      ' 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)
    

      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.

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

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.

      ' 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")
    

      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.

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

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.

      ' 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")
    

      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.

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

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.

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

      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.

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

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.

      ' 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")
    

      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.

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

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ř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")
    

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