ScriptForge.Region service

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

• Accessing locale and region-dependent settings such as number formatting, currency and timezones.

• Converting timezones and calculate Daylight Saving Time (DST) offsets.

• Transforming numbers into text in any supported language.

Definitions

Locale or Region

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.

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.

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

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.

Timezone

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 and timezones for a list of possible timezone names and IDs.

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.

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

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

The timezone and DST offsets may be positive or negative.

Service invocation

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

• As macros en Basic requiren que se cargue a biblioteca ScriptForge empregando a instrución seguinte:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Os scripts en Python requiren unha importación do módulo scriptforge:
from scriptforge import CreateScriptService

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

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

Properties

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.

DSTOffset

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

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

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

timezone: the timezone for which the offset 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.

      ' 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)
      offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 60 (minutes)
      aDateTime = DateSerial(2022, 1, 1) + TimeSerial(16, 0, 0)
      offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 0 (minutes)
    

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

LocalDateTime

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

svc.LocalD