Słužba ScriptForge.Region

Słužba Region zběrku kajkosćow a metodow k dispoziciji staja, zo by z programowanskimi aspektami wobchadźała, kotrež so na narodnu šemu a region poćahuja, na přikład:

• Přistup k nastajenjam, kotrež su wot narodneje šemy a regiona wotwisne, na přikład formatěrowanje ličbow, měna a časowe pasma.

• Přetworjenje časowych pasmow a wuličenje wotchilenjow wot lětnjeho časa (DST).

• Přetworjenje ličbow do teksta w kóždej podpěranej rěči.

Definicije

Narodna šema abo region

Znamješkowy rjećazk, kotryž rěč a kraj w formaće "rěč-KR" kombinuje. Rěčny dźěl so z 2 abo 3 pismikami w małopisanju zwuraznja, kotremuž wjazawka a 2 pismikaj slěduja, kotrež kraj reprezentuja.

Na přikład "de-AT" němskej rěči w Awstriskej wotpowěduje; "fr-BE" wotpowěduje francoskej rěči w Belgiskej a tak dale.

W někotrych situacijach dospołna narodna šema trěbna njeje a dosaha, rěč abo kraj podać.

Najwjace kajkosćow a metodoa narodnu šemu jako argument akceptuje. Jeli narodna šema podata njeje, so narodna šema wužiwarskeho powjercha wužiwa, kotraž je w kajkosći OfficeLocale słužby Platform definowana.

Časowe pasmo

Znamješkowy rjećazk we formaće „region/město“, na přikład „Europa/Berlin“ abo ID časoweho pasma kaž „UTC“ abo „GMT-8:00“. Čitajće wikistronu Lisćina časowych pasmow datoweje banki časowych pasmow (jendźelsce) z lisćinu móžnych mjenow a ID časowych pasmow.

Hdyž so njepłaćiwy znamješkowy rjećazk časoweho pasma w jednej z metodow w słužbje Region podawa, to k wuwjedźenskočasowemu zmylkej njewjedźe. Město toho metody kaž UTCDateTime a UTCNow datum a čas aktualneho dźěłoweho systema wróćeja.

Časowe wotchilenje mjez časowym pasmom a Greenwich Meridian Time (GMT) so w mjeńšinach zwuraznja.

Lětni čas (DST) je přidatne wotchilenje.

Wotchilenja časowych pasmow a lětnjeho časa móža pozitiwne kaž tež negatiwne być.

Słužbowe wuwołanje

Prjedy hač słužbu Region wužiwaće, dyrbiće biblioteku ScriptForge začitać abo importować:

• Makra Basic sej wužaduja, zo so biblioteka ScriptForge z pomocu slědowaceho přikaza začituje:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Skripty Python sej import z modula scriptforge wužaduja:
from scriptforge import CreateScriptService

Slědowace přikłady w Basic a Python słužbu Region instanciěruja a maja přistup ke kajkosći Country.

    GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
    Dim oRegion As Variant
    oRegion = CreateScriptService("Region")
    MsgBox oRegion.Country("en-US") ' Zjednoćene staty
  

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

Kajkosće

Wšě deleka nalistowane kajkosće argument locale akceptua, kotryž so jako znamješkowy rjećazk k dispoziciji staja. Někotre kajkosće trjebaja tutón argument w formaće „rěč-KR“, mjeztym zo druhe jenož "rěč" abo "KR" wočakuja.

DSTOffset

Wuličuje přidatne wotchilenje lětnjeho časa (DST) w mjeńšinach, kotrež za podaty region a podate časowe pasmo płaći.

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

localdatetime: lokalny datum a čas, zwuraznjenej jako datum.

timezone: časowe pasmo, za kotrež so wotchilenje wobličuje.

locale: Narodna šema, kotraž kraj podawa, za kotryž so wotchilenje wuličuje, pak w formaće "rěč-KR" abo w formaće "KR". Standardna hódnota je narodna šema, kotraž je w kajkosći OfficeLocale słužby Platform definowana.

      ' Wuličuje wotchilenje, kotrež za časowe pasmo "America/Los_Angeles" płaći.
      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 (mjeńšiny)
      aDateTime = DateSerial(2022, 1, 1) + TimeSerial(16, 0, 0)
      offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 0 (mjeńšiny)
    

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

LocalDateTime

Wuličuje lokalny datum a čas z datuma a časa UTC.

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

utcdatetime: datum a čas UTC, zwuraznjeny jako datumowy objekt.

timezone: časowe pasmo, za kotrež so lokalny čas wobličuje.

locale: narodna šema, kotraž kraj podawa, za kotryž so lokalny čas wobličuje, pak w formaće "rěč-KR" abo w formaće "KR". Standardna hódnota je narodna šema, kotraž je w kajkosći OfficeLocale słužby Platform definowana.

      ' June 6th, 2022 at 10:30:45 (used here as UTC time)
      Dim UTCTime As Date, localTime As Date
      UTCTime = DateSerial(2022, 6, 23) + TimeSerial(10, 30, 45)
      ' Calculates local time in Sao Paulo, Brazil
      ' June 6th, 2022 at 07: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

Converts numbers and monetary values into written text for any of the currently supported languages.

For a list of all supported languages visit the XNumberText Interface API reference.

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

number: the number to be converted into written text. It can be provided either as a numeric type or as a string. When a string is provided, it can be preceded by a prefix informing how the numbers should be written. It is also possible to include ISO 4217 currency codes. See examples below for more information.

locale: the locale defining the language into which the number will be converted to, given either in "la-CO" or "la" formats. The default value is the locale defined in the OfficeLocale property of the Platform service.

      ' Returns "one hundred five"
      Dim numText As String
      numText = oRegion.Number2Text(105, "en-US")
      ' Returns: "two point four two"
      numText = oRegion.Number2Text(2.42, "en-US")
      ' Returns: "twenty-five euro and ten cents" Notice the "EUR" currency symbol
      numText = oRegion.Number2Text("EUR 25.10", "en-US")
      ' Returns: "fifteenth"; Notice the "ordinal" prefix
      numText = oRegion.Number2Text("ordinal 15", "en-US")
    

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

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
    

The first line in the message box does not have a prefix, which means that it is the standard format. The subsequent lines include the prefix and some examples of numbers using its format.

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

Returns the offset between GMT and the given timezone and locale, in minutes.

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

timezone: the timezone for which the offset to the GMT will be calculated.

locale: the locale specifying the country for which the offset will be calculated, given either in "la-CO" or "CO" formats. The default value is the locale defined in the OfficeLocale property of the Platform service.

      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

Returns the UTC date and time considering a given local date and time in a timezone.

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

localdatetime: the local date and time in a specific timezone expressed as a date.

timezone: the timezone for which the localdatetime argument was given.

locale: the locale specifying the country for which the localdatetime argument was given, expressed either in "la-CO" or "CO" formats. The default value is the locale defined in the OfficeLocale property of the Platform service.

      ' Date/Time in Berlin, June 23, 2022 at 14:30:00
      Dim localDT As Date, utcTime As Date
      localDT = DateSerial(2022, 6, 23) + TimeSerial(14, 30, 0)
      ' The UTC date/time is June 23, 2022 at 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

Returns the current UTC date and time, given a timezone and locale.

This method uses the current date and time of your operating system to calculate the UTC time.

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

timezone: the timezone for which the current UTC time will be calculated.

locale: the locale specifying the country for which the current UTC time will be calculated, given either in "la-CO" or "CO" formats. The default value is the locale defined in the OfficeLocale property of the Platform service.

      ' Suppose the operating system time is June 23rd, 2022 at 10:42:00
      ' If the computer is in Europe/Berlin, then UTC time is June 23rd, 2022 at 08:42:00
      Dim utcTime As Date
      utcTime = oRegion.UTCNow("Europe/Berlin", "DE")
    

      utcTime = oRegion.UTCNow("Europe/Berlin", "DE")