ScriptForge.Region service

The Region service provides a collection of properties and methods to handle locale and region-related aspects of programming, such as:

Definiciones

Localidad o región

Una cadena que combina un idioma y un país en el formato "la-CO". La parte del idioma se expresa con 2 o 3 caracteres en minúscula seguidos de un guión y 2 caracteres en mayúscula que representan el país.

Por ejemplo, "en-US" corresponde al idioma inglés en Estados Unidos; "fr-BE" corresponde al idioma francés en Bélgica, y así sucesivamente.

En algunas situaciones no se requiere la configuración regional completa y sólo se puede especificar el idioma o el país.

note

La mayoría de las propiedades y métodos aceptan una configuración regional como argumento. Si no se especifica ninguna configuración regional, se utiliza la configuración regional de la interfaz de usuario, que se define en la propiedad OfficeLocale del servicio Platform.


Huso horario

Una cadena con el formato "Región/Ciudad" como "Europa/Berlín", o un ID de zona horaria como "UTC" o "GMT-8:00". Consulte la página wiki Lista de la base de datos tz y de las zonas horarias para obtener una lista de posibles nombres e ID de zonas horarias.

warning

Proporcionar una cadena de zona horaria no válida a cualquiera de los métodos del servicio Región no dará lugar a un error de ejecución. En su lugar, los métodos como UTCDateTime y UTCNow devolverán la fecha y hora actuales del sistema operativo.


La diferencia horaria entre la zona horaria y el meridiano de Greenwich (GMT) se expresa en minutos.

El horario de verano (DST) es un desplazamiento adicional.

note

La zona horaria y el horario de verano pueden ser positivos o negativos.


Invocación del servicio

Antes de utilizar el servicio Región es necesario cargar o importar la biblioteca ScriptForge:

note

• Para cargar la biblioteca ScriptForge que necesitan las macros de Basic se debe usar la siguiente declaración:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Los scripts de Python necesitan importar el módulo scriptforge:
from scriptforge import CreateScriptService


Los siguientes ejemplos en Basic y Python instancian el servicio Región y acceden a la propiedad País.

En BASIC

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

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

Propiedades

Todas las propiedades listadas a continuación aceptan un argumento locale, proporcionado como una cadena. Algunas propiedades requieren que este argumento tenga el formato "la-CO", mientras que otras pueden recibir "la" o "CO" como entrada.

Nombre

De solo lectura

Tipo

Configuración regional

Descripción

Country

String

"la‑CO"
"CO"

Devuelve el nombre en inglés del país correspondiente a la región indicada.

Currency

String

"la-CO"
"CO"

Devuelve el código de moneda ISO 4217 de la región especificada.

DatePatterns

Matriz de cadenas

"la-CO"

Devuelve una matriz de cadenas de base cero que contiene los patrones de aceptación de fechas para la región especificada.

DateSeparator

String

"la-CO"

Devuelve el separador de fechas utilizado en la región dada.

DayAbbrevNames

Matriz de cadenas

"la-CO"
"la"

Devuelve una matriz de cadenas de base cero que contiene la lista de nombres de días de la semana abreviados en el idioma especificado.

DayNames

Matriz de cadenas

"la-CO"
"la"

Devuelve una matriz de cadenas de base cero que contiene la lista de nombres de días de la semana en el idioma especificado.

DayNarrowNames

Matriz de cadenas

"la-CO"
"la"

Devuelve una matriz de cadenas de base cero que contiene la lista de las iniciales de los nombres de los días de la semana en el idioma especificado.

DecimalPoint

String

"la-CO"

Devuelve el separador decimal utilizado en los números de la región especificada.

Language

String

"la-CO"
"la"

Devuelve el nombre del idioma, en inglés, de la región especificada.

ListSeparator

String

"la-CO"

Devuelve el separador de listas utilizado en la región especificada.

MonthAbbrevNames

Matriz de cadenas

"la-CO"
"la"

Devuelve una matriz de cadenas de base cero que contiene la lista de nombres de mes abreviados en el idioma especificado.

MonthNames

Matriz de cadenas

"la-CO"
"la"

Returns a zero-based array of strings containing the list of month names in the specified language.

MonthNarrowNames

Matriz de cadenas

"la-CO"
"la"

Devuelve una matriz de cadenas de base cero que contiene la lista de nombres de meses en el idioma especificado.

ThousandSeparator

String

"la-CO"

Devuelve el separador de miles utilizado en los números de la región especificada.

TimeSeparator

String

"la-CO"

Devuelve el separador utilizado para formatear las horas en la región especificada.


Lista de métodos en el servicio Region

DSTOffset
LocalDateTime

Number2Text
TimeZoneOffset

UTCDateTime
UTCNow


DSTOffset

Calcula el desfase adicional del horario de verano (DST), en minutos, aplicable a una región y zona horaria determinadas.

Sintaxis:

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

Parámetros:

fecha y hora local: la fecha y la hora locales expresadas en forma de fecha.

zona horaria: la zona horaria para la que se calculará el desplazamiento.

local: la configuración regional que especifica el país para el que se calculará el desplazamiento, indicada en los formatos "la-CO" o "CO". El valor por defecto es la configuración regional definida en la propiedad OfficeLocale del servicio Platform.

Ejemplo:

En BASIC

      ' Calcula el desfase aplicable en la zona horaria "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)
    
En 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 la fecha y hora locales a partir de una fecha y hora UTC.

Sintaxis:

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

Parámetros:

utcdatetime: la fecha y hora UTC, expresada mediante un objeto fecha.

zona horaria: la zona horaria para la que se calculará la hora local.

locale: la configuración regional que especifica el país para el que se calculará la hora local, indicada en los formatos "la-CO" o "CO". El valor por defecto es la configuración regional definida en la propiedad OfficeLocale del servicio Platform.

Ejemplo:

En BASIC

      ' 6 de junio de 2022 a las 10:30:45 (utilizado aquí como hora UTC)
      Dim UTCTime As Date, localTime As Date
      UTCTime = DateSerial(2022, 6, 23) + TimeSerial(10, 30, 45)
      ' Calcula la hora local en São Paulo (Brasil)
      ' 6 de junio de 2022 a las 07:30:45
      localTime = oRegion.LocalDateTime(UTCTime, "America/Sao_Paulo", "BR")
    
En Python

      import datetime
      utcTime = datetime.datetime(2022, 6, 23, 10, 30, 45)
      localTime = oRegion.LocalDateTime(utcTime, "America/Sao_Paulo", "BR")
    

Number2Text

Convierte números y valores monetarios en texto escrito para cualquiera de los idiomas soportados actualmente.

tip

Para ver una lista de todos los idiomas soportados, visite la referencia de la API Interfaz XNumberText.


Sintaxis:

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

Parámetros:

número: el número a convertir en texto escrito. Puede proporcionarse como un tipo numérico o como una cadena. Cuando se proporciona una cadena, puede ir precedida de un prefijo que informa de cómo deben escribirse los números. También es posible incluir códigos de moneda ISO 4217. Para más información, consulte los ejemplos siguientes.

locale: la configuración regional que define el idioma al que se convertirá el número, dada en formato "la-CO" o "la". El valor por defecto es la configuración regional definida en la propiedad OfficeLocale del servicio Platform.

Ejemplo:

En BASIC

      ' Devuelve "ciento cinco"
      Dim numText As String
      numText = oRegion.Number2Text(105, "en-US")
      ' Devuelve: "dos punto cuatro dos"
      numText = oRegion.Number2Text(2.42, "en-US")
      ' Devuelve: "veinticinco euros y diez céntimos" Fíjate en el símbolo de la moneda "EUR"
      numText = oRegion.Number2Text("EUR 25.10", "en-US")
      ' Devuelve: "decimoquinto"; Nótese el prefijo "ordinal"
      numText = oRegion.Number2Text("ordinal 15", "en-US")
    
En 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 obtener una lista de todos los prefijos admitidos en un idioma determinado, llame a Number2Text con el argumento especial "help", como se muestra en el siguiente ejemplo:


      prefixes = oRegion.Number2Text("help")
      MsgBox prefixes
      ' Considerando la configuración regional "en-US" el cuadro de mensaje mostrará el siguiente texto
      ' uno, dos, tres
      ' ordinal: primero, segundo, tercero
      ' número ordinal: 1º, 2º, 3º
      Año: mil novecientos noventa y nueve, dos mil, dos mil uno
      Moneda (por ejemplo, USD): dos dólares estadounidenses y cincuenta centavos
      ' dinero USD: dos y 50/100 dólares americanos
    

La primera línea del cuadro de mensaje no tiene prefijo, lo que significa que se trata del formato estándar. Las líneas siguientes incluyen el prefijo y algunos ejemplos de números que utilizan su formato.

note

Cada idioma tiene su propio conjunto de prefijos admitidos.


TimeZoneOffset

Devuelve el desfase entre GMT y la zona horaria y la configuración regional dadas, en minutos.

Sintaxis:

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

Parámetros:

zona horaria: la zona horaria para la que se calculará el desfase con respecto al GMT.

locale: la configuración regional que especifica el país para el que se calculará el desplazamiento, indicada en los formatos "la-CO" o "CO". El valor por defecto es la configuración regional definida en la propiedad OfficeLocale del servicio Platform.

Ejemplo:

En BASIC

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

      offset = oRegion.TimeZoneOffset("America/New_York", "US") # -300
      offset = oRegion.TimeZoneOffset("Europe/Berlin", "DE") # 60
    

UTCDateTime

Devuelve la fecha y hora UTC teniendo en cuenta una fecha y hora local dada en una zona horaria.

Sintaxis:

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

Parámetros:

localdatetime: la fecha y hora local en una zona horaria específica expresada como una fecha.

zona horaria: la zona horaria para la que se dio el argumento localdatetime.

local: la configuración regional que especifica el país para el que se dio el argumento localdatetime, expresado en los formatos "la-CO" o "CO". El valor por defecto es la configuración regional definida en la propiedad OfficeLocale del servicio Platform.

Ejemplo:

En BASIC

      ' Fecha/hora en Berlín, 23 de junio de 2022 a las 14:30:00
      Dim localDT As Date, utcTime As Date
      localDT = DateSerial(2022, 6, 23) + TimeSerial(14, 30, 0)
      ' La fecha/hora UTC es el 23 de junio de 2022 a las 12:30:00
      utcTime = oRegion.UTCDateTime(localDT, "Europe/Berlin", "DE")
    
En Python

      importar datetime
      localDT = datetime.datetime(2022, 6, 23, 14, 30, 0)
      utcTime = oRegion.UTCDateTime(localDT, "Europe/Berlin", "DE")
    

UTCNow

Devuelve la fecha y la hora actuales en UTC tras otorgarse un huso horario y una región.

Este método utiliza la fecha y la hora actuales del sistema operativo para calcular la hora UTC.

Sintaxis:

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

Parámetros:

zona horaria: la zona horaria para la que se calculará la hora UTC actual.

locale: la configuración regional que especifica el país para el que se calculará la hora UTC actual, dada en los formatos "la-CO" o "CO". El valor por defecto es la configuración regional definida en la propiedad OfficeLocale del servicio Platform.

Ejemplo:

En BASIC

      ' Supongamos que la hora del sistema operativo es el 23 de junio de 2022 a las 10:42:00
      ' Si el ordenador está en Europa/Berlín, la hora UTC es el 23 de junio de 2022 a las 08:42:00
      Dim utcTime As Date
      utcTime = oRegion.UTCNow("Europe/Berlin", "DE")
    
En Python

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