Sumário

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

##### 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: 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.

### Exemplo:

##### Em Basic

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

##### Em Python

          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.

### Sintaxe:

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

### Parâmetros:

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.

### Exemplo:

##### Em Basic

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

##### Em Python

          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.

### Sintaxe:

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

### Parâmetros:

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.

### 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

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

### Sintaxe:

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

### Parâmetros:

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.

### Exemplo:

##### Em Basic

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

##### Em Python

          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.

### Sintaxe:

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

### Parâmetros:

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.

### Exemplo:

##### Em Basic

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

##### Em Python

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

Tópicos relacionados

Serviço ScriptForge.Platform