ScriptForge.Region serviço

O serviço Region disponibiliza um conjunto de propriedades e métodos para lidar com aspetos da programação relacionados com as configurações regionais e de localização, tais como:

Aceder a definições dependentes da localização e da região, tais como a formatação de números, a moeda e os fusos horários.
Converter fusos horários e calcular os desfasamentos do horário de verão (DST).
Converter números em texto em qualquer idioma suportado.

Definições

Localização ou região

Uma cadeia de caracteres que combina um idioma e um país no formato «la-CO». A parte relativa ao idioma é expressa por 2 ou 3 caracteres minúsculos, seguidos de um traço e de 2 caracteres maiúsculos que representam o país.

Por exemplo, «en-US» corresponde ao inglês dos Estados Unidos; «fr-BE» corresponde ao francês da Bélgica, e assim por diante.

Em algumas situações, não é necessário indicar a localização completa, podendo especificar-se apenas o idioma ou o país.

A maioria das propriedades e métodos aceita uma localização como argumento. Se não for especificada nenhuma localização, é utilizada a localização da interface do utilizador, que está definida na propriedade OfficeLocale do serviço Platform.

Fuso horário

Uma cadeia de caracteres no formato «Região/Cidade», como «Europa/Berlim», ou um identificador de fuso horário, como «UTC» ou «GMT-8:00». Consulte a página wiki Lista de fusos horários da base de dados tz para obter uma lista dos possíveis nomes e IDs de fusos horários.

A introdução de uma cadeia de caracteres de fuso horário inválida em qualquer um dos métodos do serviço Region não resultará num erro de execução. Em vez disso, métodos como UTCDateTime e UTCNow devolverão a data e a hora atuais do sistema operativo.

A diferença horária entre o fuso horário e a Hora Média de Greenwich (GMT) é expressa em minutos.

O horário de verão (DST) é um desfasamento adicional.

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

Chamada de serviço

Antes de utilizar o serviço Region, é necessário carregar ou importar a biblioteca ScriptForge:

• As macros básicas requerem o carregamento da biblioteca ScriptForge através da seguinte instrução:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Os scripts Python requerem a importação do módulo scriptforge:
from scriptforge import CreateScriptService

Os exemplos abaixo, em Basic e Python, instanciam o serviço Region e acedem à propriedade Country.

Em Basic


    GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
    Dim oRegion As Variant
    oRegion = CreateScriptService("Region")
    MsgBox oRegion.Country("en-US") ' Estados Unidos

Em Python


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

Características

Todas as propriedades listadas abaixo aceitam um argumento locale, fornecido como uma cadeia de caracteres. Algumas propriedades exigem que este argumento tenha o formato «la-CO», enquanto outras podem aceitar «la» ou «CO» como entrada.

Nome	Apenas leitura	Tipo	Local	Descrição
Country	Sim	String	"la‑CO" "CO"	Devolve o nome do país em inglês correspondente a uma determinada região.
Currency	Sim	String	"la-CO" "CO"	Devolve o código de moeda ISO 4217 da região especificada.
DatePatterns	Sim	Matriz de cadeias de caracteres	"la-CO"	Devolve uma matriz de cadeias de caracteres, com índice a partir de zero, que contém os padrões de aceitação de datas para a região especificada.
DateSeparator	Sim	String	"la-CO"	Devolve o separador de data utilizado na região indicada.
DayAbbrevNames	Sim	Matriz de cadeias de caracteres	"la-CO" "la"	Devolve um array de cadeias de caracteres, com índice a partir de zero, que contém a lista de nomes abreviados dos dias da semana no idioma especificado.
DayNames	Sim	Matriz de cadeias de caracteres	"la-CO" "la"	Devolve um array de cadeias de caracteres, com índice a partir de zero, que contém a lista dos nomes dos dias da semana no idioma especificado.
DayNarrowNames	Sim	Matriz de cadeias de caracteres	"la-CO" "la"	Devolve uma matriz de cadeias de caracteres, com índice a partir de zero, que contém a lista das iniciais dos nomes dos dias da semana no idioma especificado.
DecimalPoint	Sim	String	"la-CO"	Devolve o separador decimal utilizado nos números na região especificada.
Language	Sim	String	"la-CO" "la"	Devolve o nome, em inglês, do idioma da região especificada.
ListSeparator	Sim	String	"la-CO"	Devolve o separador de lista utilizado na região especificada.
MonthAbbrevNames	Sim	Matriz de cadeias de caracteres	"la-CO" "la"	Devolve um array de cadeias de caracteres, com índice a partir de zero, que contém a lista de nomes abreviados dos meses no idioma especificado.
MonthNames	Sim	Matriz de cadeias de caracteres	"la-CO" "la"	Devolve uma matriz de cadeias de caracteres, com índice a partir de zero, que contém a lista dos nomes dos meses no idioma especificado.
MonthNarrowNames	Sim	Matriz de cadeias de caracteres	"la-CO" "la"	Devolve uma matriz de cadeias de caracteres, com índice a partir de zero, que contém a lista das iniciais dos nomes dos meses no idioma especificado.
ThousandSeparator	Sim	String	"la-CO"	Devolve o separador de milhares utilizado nos números na região especificada.
TimeSeparator	Sim	String	"la-CO"	Devolve o separador utilizado para formatar as horas na região especificada.

Lista de métodos do serviço «Região»
DSTOffset LocalDateTime	Number2Text TimeZoneOffset	UTCDateTime UTCNow

DSTOffset

Calcula o desfasamento adicional do horário de verão (DST), em minutos, aplicável a uma determinada região e fuso horário.

Sintaxe:

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

Parâmetros:

localdatetime: a data e a hora locais expressas como uma data.

fuso horário: o fuso horário para o qual será calculado o desfasamento.

locale: a localização que especifica o país para o qual o desfasamento será calculado, indicada nos formatos «la-CO» ou «CO». O valor predefinido é a localização definida na propriedade OfficeLocale do serviço Platform.

Exemplo:

Em Basic


      ' Calcula o desfasamento aplicável no 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 a hora locais a partir de uma data e hora em UTC.

Sintaxe:

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

Parâmetros:

utcdatetime: a data e a hora em UTC, expressas através de um objeto de data.

fuso horário: o fuso horário para o qual será calculada a hora local.

locale: a localização que especifica o país para o qual a hora local será calculada, indicada nos formatos «la-CO» ou «CO». O valor predefinido é a localização definida na propriedade OfficeLocale do serviço Platform.

Exemplo:

Em Basic


      ' 6 de junho de 2022 às 10:30:45 (utilizado aqui como hora UTC)
      Dim UTCTime As Date, localTime As Date
      UTCTime = DateSerial(2022, 6, 23) + TimeSerial(10, 30, 45)
      ' Calcula a hora 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 em qualquer um dos idiomas atualmente suportados.

Para obter uma lista de todas as línguas suportadas, consulte a referência da API da Interface XNumberText.

Sintaxe:

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

Parâmetros:

número: o número a converter em texto escrito. Pode ser fornecido como um valor numérico ou como uma cadeia de caracteres. Quando é fornecida uma cadeia de caracteres, esta pode ser precedida por um prefixo que indique como os números devem ser escritos. Também é possível incluir códigos de moeda ISO 4217. Consulte os exemplos abaixo para obter mais informações.

locale: a localização que define o idioma para o qual o número será convertido, indicada nos formatos «la-CO» ou «la». O valor predefinido é a localização definida na propriedade OfficeLocale do serviço Platform.

Exemplo:

Em Basic


      ' Devolve «cento e cinco»
      Dim numText As String
      numText = oRegion.Number2Text(105, "en-US")
      ' Devolve: «dois vírgula quatro dois»
      numText = oRegion.Number2Text(2,42, "pt-PT")
      ' Responde: «vinte e cinco euros e dez cêntimos». Repare no símbolo da moeda «EUR»
      numText = oRegion.Number2Text("EUR 25.10", "en-US")
      ' Devolve: «décimo quinto»; Repare no prefixo «ordinal»
      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")

Para obter uma lista de todos os prefixos suportados num determinado idioma, chame Number2Text com o argumento especial «help». No exemplo abaixo, suponha que a sua localização está definida como «en-US»; nesse caso, a lista de prefixos disponíveis para «en-US» será apresentada 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 da caixa de mensagem não tem prefixo, o que significa que se trata do formato padrão. As linhas seguintes incluem o prefixo e alguns exemplos de números que utilizam esse formato.

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

Para obter a lista de prefixos de um idioma ou localização específicos, estes podem ser especificados como segundo argumento em Number2Text. O exemplo abaixo mostra os prefixos disponíveis para a localização «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

Devolve a diferença, em minutos, entre o GMT e o fuso horário e a localização especificados.

Sintaxe:

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

Parâmetros:

fuso horário: o fuso horário para o qual será calculado o desfasamento em relação ao GMT.

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

Devolve a data e a hora UTC com base numa data e hora locais específicas num determinado fuso horário.

Sintaxe:

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

Parâmetros:

localdatetime: a data e a hora locais num fuso horário específico, expressas como uma data.

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

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


      ' Data e 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)
      ' A data e hora em UTC são 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

Devolve a data e a hora atuais em UTC, com base num fuso horário e numa configuração regional.

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

Sintaxe:

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

Parâmetros:

fuso horário: o fuso horário em relação ao qual será calculada a hora UTC atual.

locale: a localização que especifica o país para o qual a hora UTC atual será calculada, indicada nos formatos «la-CO» ou «CO». O valor predefinido é a localização definida na propriedade OfficeLocale do serviço Platform.

Exemplo:

Em Basic


      ' Suponhamos que a data e hora do sistema operativo sejam 23 de junho de 2022, às 10:42:00
      ' Se o computador estiver na Europa/Berlim, então a hora 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")

ScriptForge.Platform serviço