Ajuda do LibreOffice 24.8
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.
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.
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.
Antes de utilizar o serviço Region, a biblioteca ScriptForge deve ser carregada ou importada:
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"))
  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" | Retorna o nome do país em inglês correspondente à região informada. | 
| Currency | Sim | String | "la-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" | 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" | 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" | 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" | 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" | 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" | 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" | 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 | ||
|---|---|---|
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)
    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")
    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.º
    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
    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")
    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")