Servicio ScriptForge.Region

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

Acceder a parámetros dependientes de la configuración regional, tales como el formato numérico, la moneda y los husos horarios.
Convertir husos horarios y calcular diferencias respecto a horarios de verano.
Transformación de números en texto en cualquier idioma compatible.

Definiciones

Localidad o región

Una cadena que combina un idioma y un país en el formato «xx-XX». La parte relativa al idioma se expresa con dos o tres caracteres minúsculos, seguidos de un guion y dos caracteres mayúsculos que representan el país.

Por ejemplo, «en-US» corresponde al idioma inglés en Estados Unidos y «es-MX» corresponde a la lengua española en México.

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

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 «Europe/Berlin», o el identificador de un huso horario, como «UTC» o «GMT-8:00». Consulte la Lista de husos horarios de la base de datos tz (en inglés) de Wikipedia para obtener una lista de los nombres e identificadores de husos horarios posibles.

Proporcionar una cadena de huso horario no válida a cualquiera de los métodos del servicio Region 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 el huso horario y el meridiano de Greenwich (GMT) se expresa en minutos.

El horario de verano (DST) es una diferencia adicional.

Las diferencias por huso horario y por horario de verano pueden ser positivas o negativas.

Invocación del servicio

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

• 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 enumeradas a continuación aceptan un argumento locale, proporcionado como una cadena. Algunas propiedades requieren que este argumento tenga el formato «xx-XX» (idioma-PAÍS), mientras que otras pueden recibir «xx» o «XX» como entrada.

Nombre	De solo lectura	Tipo	Configuración regional	Descripción
Country	Sí	String	"la‑CO" "CO"	Devuelve el nombre en inglés del país correspondiente a la región indicada.
Currency	Sí	String	"la-CO" "CO"	Devuelve el código ISO 4217 de la moneda de la región especificada.
DatePatterns	Sí	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	Sí	String	"la-CO"	Devuelve el separador de fechas utilizado en la región dada.
DayAbbrevNames	Sí	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	Sí	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	Sí	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	Sí	String	"la-CO"	Devuelve el separador decimal utilizado en los números de la región especificada.
Language	Sí	String	"la-CO" "la"	Devuelve el nombre del idioma, en inglés, de la región especificada.
ListSeparator	Sí	String	"la-CO"	Devuelve el separador de listas utilizado en la región especificada.
MonthAbbrevNames	Sí	Matriz de cadenas	"la-CO" "la"	Devuelve una matriz de cadenas indizada a partir de cero, la cual contiene los nombres de los meses abreviados en la lengua que se especifique.
MonthNames	Sí	Matriz de cadenas	"la-CO" "la"	Devuelve una matriz de cadenas indizada a partir de cero, la cual contiene los nombres de los meses en la lengua que se especifique.
MonthNarrowNames	Sí	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	Sí	String	"la-CO"	Devuelve el separador de miles utilizado en los números de la región especificada.
TimeSeparator	Sí	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 la diferencia adicional debida al horario de verano (DST), en minutos, aplicable a una región y huso horario determinados.

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.

timezone: el huso horario para el que se calculará la diferencia.

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 la diferencia aplicable en el huso horario «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.

timezone: el huso horario para el 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 en cualquiera de los idiomas admitidos actualmente.

Para ver una lista de todos los idiomas admitidos, visite la referencia de la API de la interfaz XNumberText (en inglés).

Sintaxis:

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

Parámetros:

number: el número que se debe 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 monetarios 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 «xx-XX» o «xx». El valor predeterminado 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, "es")
      ' Devuelve: «two point four two»
      numText = oRegion.Number2Text(2.42, "en-US")
      ' Devuelve: «vint-i-cinc euros amb deu cèntims». Observe el símbolo de la moneda «EUR»
      numText = oRegion.Number2Text("EUR 25.10", "ca")
      ' Devuelve: «quinzième». Observe el prefijo «ordinal»
      numText = oRegion.Number2Text("ordinal 15", "fr-CH")

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

To get a list of all supported prefixes in a given language, call Number2Text with the special "help" argument. In the example below, assume your locale is set to "en-US", then the list of available prefixes for "en-US" will be shown by 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

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.

Cada idioma tiene su propio conjunto de prefijos admitidos. La cantidad de prefijos disponibles puede variar en función del idioma.

Para obtener la lista de prefijos de un idioma o configuración regional en específico, se puede definir el segundo argumento en Number2Text. El ejemplo siguiente muestra los prefijos disponibles en la configuración regional «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

Devuelve la diferencia entre GMT y el huso horario y la configuración regional que se han proporcionado, en minutos.

Sintaxis:

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

Parámetros:

timezone: el huso horario para el que se calculará la diferencia 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 un huso horario.

Sintaxis:

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

Parámetros:

localdatetime: la fecha y hora locales en un huso horario específico, expresadas como una fecha.

timezone: el huso horario para el 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


      import 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:

timezone: el huso horario para el 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")

Servicio ScriptForge.Platform