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:

• Acessar configurações dependentes da localidade e região como o formato de números, moeda e fuso horário.

• Converter fusos horários e calcular deslocamentos de horário de verão.

• Transformar números em texto em qualquer um dos idiomas suportados.

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.

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

Um valor string no formato "Region/City" como por exemplo "Europe/Berlin", ou um identificador de fuso horário como "UTC" ou "GMT-8:00". Leia a página Wiki List of tz database timezones para uma lista de possíveis nomes e identificadores de fuso horário.

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.

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:

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

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

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.

DSTOffset

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

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

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.

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

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

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

utcdatetime: a data e horário do UTC, expresso usando um objeto de data.

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

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

      ' 6 de junho de 2022 às 10:30:45 (usado aqui como horário UTC)
      Dim UTCTime As Date, localTime As Date
      UTCTime = DateSerial(2022, 6, 23) + TimeSerial(10, 30, 45)
      ' Calcula o horário local em São Paulo, Brasil
      ' 6 de junho de 2022 às 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

Converte números e valores monetários em texto escrito para qualquer um dos idiomas suportados.

Para uma lista com todos os idiomas suportados visite a página de referência da API sobre a XNumberText Interface.

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

number: número a ser convertido em texto escrito. Pode ser fornecido tanto em tipo numérico como em uma string. Quando uma string for fornecida, ela pode ser precedida por um prefixo informando como os números devem ser escritos. Também é possível incluir códigos de moeda seguindo a norma ISO 4217. Veja os exemplos abaixo para mais informações:

locale: localidade que define o idioma para o qual o número será convertido, dado no formato "la-CO" ou "la". O valor padrão é a localidade definida na propriedade OfficeLocale do serviço Platform.

      ' Retorna "one hundred five"
      Dim numText As String
      numText = oRegion.Number2Text(105, "en-US")
      ' Retorna: "dois vírgula quarenta e dois"
      numText = oRegion.Number2Text(2.42, "pt-BR")
      ' Retorna: "twenty-five euro and ten cents". Note o símbolo de moeda "EUR".
      numText = oRegion.Number2Text("EUR 25.10", "en-US")
      ' Retorna: "décimo quinto"; Note o prefixo "ordinal".
      numText = oRegion.Number2Text("ordinal 15", "pt-BR")
    

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

Para obter uma lista com todos os prefixos suportados em um dado idioma, chame Number2Text com o argumento especial "help". No exemplo abaixo, suponha que sua localidade é "en-US", então a lista de prefixos para "en-US" será mostrada pelo 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
    

A primeira linha na caixa de mensagem não possui um prefixo, o que significa que esse é o formato padrão. As linhas seguintes incluem o prefixo e alguns exemplos de números usando o formato.

Cada idioma possui seu próprio conjunto de prefixos suportados. O número de prefixos disponíveis pode variar para cada idioma.

Para obter a lista de prefixos para um idioma ou localidade específico, especifique-o como o segundo argumento do método Number2Text. O exemplo abaixo mostra os prefixos disponíveis para a localidade "pt-BR":

      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

Retorna o deslocamento entre o horário GMT e um dado fuso horário e localidade, em minutos.

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

timezone: fuso horário para o qual o deslocamento com relação ao horário GMT 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.

      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

Retorna a data e hora UTC considerando uma data e hora local em um fuso horário.

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

localdatetime: data e hora local em um fuso horário específico expresso como um objeto de data.

timezone: fuso horário para o qual o argumento localdatetime foi especificado.

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

      ' Data/Hora em Berlim, 23 de junho de 2022 às 14:30:00
      Dim localDT As Date, utcTime As Date
      localDT = DateSerial(2022, 6, 23) + TimeSerial(14, 30, 0)
      ' Data/hora UTC é 23 de junho de 2022 às 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

Retorna o a data/hora UTC atual, dado um fuso horário e localidade.

Este método usa a data e hora atuais do seu sistema operacional para calcular a data e hora UTC.

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

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

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

      ' Considere que o horário do sistema operacional é 23 de junho de 2022 às 10:42:00
      ' Se o computador está na região Europe/Berlin, então o horário UTC é 23 de junho de 2022 às 08:42:00
      Dim utcTime As Date
      utcTime = oRegion.UTCNow("Europe/Berlin", "DE")
    

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