Serviço ScriptForge.Region

O serviço Region fornece um conjunto de propriedades e métodos para manipular aspectos de programação relacionados à localidade e região, tais como:

Definições

Localidade ou Região

Valor String combinando um idioma e país no formato "la-CO" (language-COUNTRY). A parte do idioma é expressa usando 2 ou 3 caracteres minúsculos seguidos de um traço "-" e 2 caracteres maiúsculos representando o país.

Por exemplo, "en-US" corresponde ao idioma inglês nos Estados Unidos; "pt-BR" corresponde ao idioma português no Brasil, e assim por diante.

Em algumas situações a localidade completa não é necessária e apenas o idioma ou o país podem ser especificados.

note

A maioria das propriedades e métodos aceitam uma localidade como argumento. Se nenhuma localidade for especificada, então a localidade definida para a interface do usuário é usada. Tal localidade pode ser acessada pela propriedade OfficeLocale do serviço Platform.


Fuso horário

Valor String no formato "Região/Cidade" como por exemplo "Europe/Berlin", ou um identificador de fuso horário como "UTC" ou "GMT-08:00". Leia a página Wiki List of tz database and timezones para uma lista de possíveis nomes e identificadores de fuso horário.

warning

Fornecer uma String de fuso horário inválida para qualquer método do serviço Region não resultará em um erro de tempo de execução. Em vez disso, métodos como UTCDateTime e UTCNow retornarão a data e horário atual do sistema operacional.


O deslocamento de tempo entre o fuso horário e o horário do Meridiano de Greenwich (Greenwich Meridian Time, GMT) é expresso em minutos.

O horário de verão (Daylight Saving Time, DST) é um deslocamento de tempo adicional.

note

Os deslocamentos de fuso horário e de horário de verão podem ser positivos ou negativos.


Invocação do serviço

Antes de utilizar o serviço Region, a biblioteca ScriptForge deve ser carregada ou importada:

note

• Macros BASIC precisam carregar a biblioteca ScriptForge usando a seguinte instrução:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Scripts Python exigem uma importação do módulo scriptforge:
from scriptforge import CreateScriptService


Os exemplos abaixo em Basic e Python criam uma instância do serviço Region e acessam sua propriedade Country.

Em Basic

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

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

Propriedades

Todas as propriedades listadas abaixo aceitam um argumento locale fornecido como uma String. Algumas propriedades necessitam deste argumento no formato "la-CO", ao passo que outros podem receber apenas o idioma "la" ou o país "CO" como entrada.

Nome

Somente leitura

Tipo

Localidade

Descrição

Country

Sim

String

"la‑CO"
"CO"

Retorna o nome do país em inglês correspondente à região informada.

Currency

Sim

String

"la-CO"
"CO"

Retorna o código de moeda ISO 4217 correspondente à região especificada.

DatePatterns

Sim

Array de Strings

"la-CO"

Retorna um Array de Strings indexado a partir de zero contendo os padrões de aceitação de dadas de uma região.

DateSeparator

Sim

String

"la-CO"

Retorna o separador de datas usado na região especificada.

DayAbbrevNames

Sim

Array de Strings

"la-CO"
"la"

Retorna um Array de Strings indexado a partir de zero contendo a lista das abreviações dos dias da semana no idioma especificado.

DayNames

Sim

Array de Strings

"la-CO"
"la"

Retorna um Array de Strings indexado a partir de zero contendo a lista dos nomes dos dias da semana no idioma especificado.

DayNarrowNames

Sim

Array de Strings

"la-CO"
"la"

Retorna um Array de Strings indexado a partir de zero contendo a lista das iniciais dos nomes dos dias da semana no idioma especificado.

DecimalPoint

Sim

String

"la-CO"

Retorna o separador de casas decimais usado em números na região especificada.

Language

Sim

String

"la-CO"
"la"

Retorna o nome do idioma, em inglês, da região especificada.

ListSeparator

Sim

String

"la-CO"

Retorna o separador de listas usado na região especificada.

MonthAbbrevNames

Sim

Array de Strings

"la-CO"
"la"

Retorna um Array de Strings indexado a partir de zero contendo a lista das abreviações dos nomes dos meses no idioma especificado.

MonthNames

Sim

Array de Strings

"la-CO"
"la"

Retorna um Array de Strings indexado a partir de zero contendo a lista dos nomes dos meses no idioma especificado.

MonthNarrowNames

Sim

Array de Strings

"la-CO"
"la"

Retorna um Array de Strings indexado a partir de zero contendo a lista das iniciais dos nomes dos meses no idioma especificado.

ThousandSeparator

Sim

String

"la-CO"

Retorna o separador de milhares usado em números na região especificada.

TimeSeparator

Sim

String

"la-CO"

Retorna o separador usado para formatar horas na região especificada.


Lista de Métodos no Serviço Region

DSTOffset
LocalDateTime

Number2Text
TimeZoneOffset

UTCDateTime
UTCNow


DSTOffset

Calcula o deslocamento adicional de horário de verão, em minutos, que é aplicável a uma região e fuso horário.

Sintaxe:

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

Parâmetros:

localdatetime: data e horário local expressos como um objeto de data.

timezone: fuso horário para o qual o deslocamento será calculado.

locale: localidade especificando o país para o qual o deslocamento será calculado, dado no formato "la-CO" ou "CO". O valor padrão é a localidade definida na propriedade OfficeLocale do serviço Platform.

Exemplo:

Em Basic

      ' Calcula o deslocamento aplicável ao fuso horário "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 (minutos)
      aDateTime = DateSerial(2022, 1, 1) + TimeSerial(16, 0, 0)
      offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 0 (minutos)
    
Em Python

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

LocalDateTime

Calcula a data e hora local a partir de uma data e hora UTC (Coordinated Universal Time).

Sintaxe:

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

Parâmetros:

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

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

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.

Exemplo:

Em Basic

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

      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.

tip

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


Sintaxe:

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

Parâmetros:

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.

Exemplo:

Em Basic

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

      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, as shown in the example below:


      prefixes = oRegion.Number2Text("help")
      MsgBox prefixes
      ' Considering the "en-US" locale the message box will show the following text
      ' 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.

note

Each language has its own set of supported prefixes.


TimeZoneOffset

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

Sintaxe:

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

Parâmetros:

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.

Exemplo:

Em Basic

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

      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.

Sintaxe:

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

Parâmetros:

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.

Exemplo:

Em Basic

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

      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.

Sintaxe:

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

Parâmetros:

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.

Exemplo:

Em Basic

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

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