H7HZZ‖ScriptForge.Region service

w3WgP‖The Region service provides a collection of properties and methods to handle locale and region-related aspects of programming, such as:

9nRv7‖Definitions

sGNu7‖Locale or Region

FiW7z‖A string combining a language and a country in the format "la-CO". The language part is expressed with 2 or 3 lowercase characters followed by a dash and 2 uppercase characters representing the country.

GQEGW‖For instance, "en-US" corresponds to the English language in the United States; "fr-BE" corresponds to the French language in Belgium, and so forth.

CQYAX‖On some situations the full locale is not required and only the language or country may be specified.

note

ujAAt‖Most properties and methods accept a locale as argument. If no locale is specified, then the user-interface locale is used, which is defined in the OfficeLocale property of the Platform service.


6ToTC‖Timezone

GGBdC‖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

exa3B‖Providing an invalid timezone string to any of the methods in the Region service will not result in a runtime error. Instead, methods as UTCDateTime and UTCNow will return the current operating system date and time.


7GTLU‖The time offset between the timezone and the Greenwich Meridian Time (GMT) is expressed in minutes.

ottwV‖The Daylight Saving Time (DST) is an additional offset.

note

yXHrp‖The timezone and DST offsets may be positive or negative.


EyNvN‖Service invocation

F9Wnj‖Before using the Region service the ScriptForge library needs to be loaded or imported:

note

gF8D8‖• Basic macros require to load ScriptForge library using the following statement:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python scripts require an import from scriptforge module:
from scriptforge import CreateScriptService


7AXFZ‖The examples below in Basic and Python instantiate the Region service and access the Country property.

3aa4B‖In Basic

    GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
    Dim oRegion As Variant
    oRegion = CreateScriptService("Region")
    69CF7‖MsgBox oRegion.Country("en-US") ' United States
  
BenDd‖In Python

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

FDNKL‖Properties

VEB3D‖All properties listed below accept a locale argument, provided as a string. Some properties require this argument to be in the format "la-CO", whereas others may receive "la" or "CO" as input.

vzB4T‖Name

ay9iH‖Readonly

rBUEm‖Type

FpD5h‖Locale

FxnFK‖Description

Country

4Ss2G‖Yes

String

"la‑CO"
"CO"

ExbtG‖Returns the country name in English corresponding to a given region.

Currency

FN4XC‖Yes

String

"la-CO"
"CO"

vpDwN‖Returns the ISO 4217 currency code of the specified region.

DatePatterns

Aqcuy‖Yes

6cgk7‖String array

"la-CO"

Jhkc3‖Returns a zero-based array of strings containing the date acceptance patterns for the specified region.

DateSeparator

T4sUQ‖Yes

String

"la-CO"

vAJYH‖Returns the date separator used in the given region.

DayAbbrevNames

QKyGp‖Yes

jSVY8‖String array

"la-CO"
"la"

CnTuU‖Returns a zero-based array of strings containing the list of abbreviated weekday names in the specified language.

DayNames

jRUnx‖Yes

CGeKU‖String array

"la-CO"
"la"

tjGhP‖Returns a zero-based array of strings containing the list of weekday names in the specified language.

DayNarrowNames

gVevH‖Yes

hL4sb‖String array

"la-CO"
"la"

GHdGz‖Returns a zero-based array of strings containing the list of the initials of weekday names in the specified language.

DecimalPoint

TFzKG‖Yes

String

"la-CO"

CWLzi‖Returns the decimal separator used in numbers in the specified region.

Language

pqWDC‖Yes

String

"la-CO"
"la"

droDW‖Returns the name of the language, in English, of the specified region.

ListSeparator

ojXGP‖Yes

String

"la-CO"

a4SKv‖Returns the list separator used in the specified region.

MonthAbbrevNames

vUwhJ‖Yes

79WHE‖String array

"la-CO"
"la"

Dz2X6‖Returns a zero-based array of strings containing the list of abbreviated month names in the specified language.

MonthNames

NvQaB‖Yes

ZMsz8‖String array

"la-CO"
"la"

EbAXk‖Returns a zero-based array of strings containing the list of month names in the specified language.

MonthNarrowNames

GeqFt‖Yes

wGD4y‖String array

"la-CO"
"la"

RisPb‖Returns a zero-based array of strings containing the list of the initials of month names in the specified language.

ThousandSeparator

DBDyW‖Yes

String

"la-CO"

fLZD2‖Returns the thousands separator used in numbers in the specified region.

TimeSeparator

AUNfp‖Yes

String

"la-CO"

MjrCr‖Returns the separator used to format times in the specified region.


Bog4G‖List of Methods in the Region Service

DSTOffset
LocalDateTime

Number2Text
TimeZoneOffset

UTCDateTime
UTCNow


DSTOffset

szpDY‖Computes the additional Daylight Saving Time (DST) offset, in minutes, that is applicable to a given region and timezone.

FVEx2‖Syntax:

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

WADQ4‖Parameters:

CbDHo‖localdatetime: the local date and time expressed as a date.

cA2tD‖timezone: the timezone for which the offset will be calculated.

LD3qm‖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.

EFSA4‖Example:

3aa4B‖In Basic

      cBF4y‖' Calculates the offset applicable in the "America/Los_Angeles" timezone
      Dim aDateTime As Date, offset As Integer
      aDateTime = DateSerial(2022, 7, 1) + TimeSerial(16, 0, 0)
      XYu4u‖offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 60 (minutes)
      aDateTime = DateSerial(2022, 1, 1) + TimeSerial(16, 0, 0)
      CfiFK‖offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 0 (minutes)
    
BenDd‖In Python

      import datetime
      aDateTime = datetime.datetime(2022, 7, 1, 16, 0, 0)
      4CkKJ‖offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 60 (minutes)
      aDateTime = datetime.datetime(2022, 1, 1, 16, 0, 0)
      nkcRi‖offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 0 (minutes)
    

LocalDateTime

BbUgj‖Computes the local date and time from a UTC date and time.

FVEx2‖Syntax:

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

WADQ4‖Parameters:

v4YSt‖utcdatetime: the UTC date and time, expressed using a date object.

i63on‖timezone: the timezone for which the local time will be calculated.

tzvsE‖locale: the locale specifying the country for which the local 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.

EFSA4‖Example:

3aa4B‖In Basic

      8UTFQ‖' 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)
      Hcjqt‖' Calculates local time in Sao Paulo, Brazil
      yhKtd‖' June 6th, 2022 at 07:30:45
      localTime = oRegion.LocalDateTime(UTCTime, "America/Sao_Paulo", "BR")
    
BenDd‖In Python

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

Number2Text

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

tip

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


FVEx2‖Syntax:

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

WADQ4‖Parameters:

xTUD6‖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.

cNDim‖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.

EFSA4‖Example:

3aa4B‖In Basic

      QeBpA‖' Returns "one hundred five"
      Dim numText As String
      7xovc‖numText = oRegion.Number2Text(105, "en-US")
      UGGvv‖' Returns: "two point four two"
      Xr7no‖numText = oRegion.Number2Text(2.42, "en-US")
      7hYbk‖' Returns: "twenty-five euro and ten cents" Notice the "EUR" currency symbol
      DBPc8‖numText = oRegion.Number2Text("EUR 25.10", "en-US")
      pd3Fm‖' Returns: "fifteenth"; Notice the "ordinal" prefix
      ggt2A‖numText = oRegion.Number2Text("ordinal 15", "en-US")
    
BenDd‖In Python

      YQCCF‖numText = oRegion.Number2Text(105, "en-US")
      FTGnF‖numText = oRegion.Number2Text(2.42, "en-US")
      RCDq5‖numText = oRegion.Number2Text("EUR 25.10", "en-US")
      vtGFv‖numText = oRegion.Number2Text("ordinal 15", "en-US")
    

3T93o‖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
    

RBkxp‖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.

note

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


gcMPN‖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

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

FVEx2‖Syntax:

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

WADQ4‖Parameters:

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

XuX3E‖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.

EFSA4‖Example:

3aa4B‖In Basic

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

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

UTCDateTime

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

FVEx2‖Syntax:

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

WADQ4‖Parameters:

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

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

zSttY‖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.

EFSA4‖Example:

3aa4B‖In Basic

      y3NSm‖' 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)
      HjSnk‖' The UTC date/time is June 23, 2022 at 12:30:00
      utcTime = oRegion.UTCDateTime(localDT, "Europe/Berlin", "DE")
    
BenDd‖In Python

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

UTCNow

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

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

FVEx2‖Syntax:

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

WADQ4‖Parameters:

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

BHESq‖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.

EFSA4‖Example:

3aa4B‖In Basic

      FWSJp‖' Suppose the operating system time is June 23rd, 2022 at 10:42:00
      CWY76‖' 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")
    
BenDd‖In Python

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