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:

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.

note

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

A string in the format "Region/City" such as "Europe/Berlin", or a timezone ID such as "UTC" or "GMT-8:00". Refer to the wiki page List of tz database timezones for a list of possible timezone names and IDs.

warning

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

note

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í:

note

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

tip

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

To get a list of all supported prefixes in a given language, call Number2Text with the special "help" argument. In the example below, assume your locale is set to "en-US", then the list of available prefixes for "en-US" will be shown by MsgBox:


      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.

note

Each language has its own set of supported prefixes. The number of available prefixes may vary from language to language.


To get the list of prefixes for a specific language or locale, it can be specified as the second argument in Number2Text. The example below shows the available prefixes available for the "pt-BR" locale:


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