Contenido

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

Para obtener una lista de todos los prefijos admitidos en un idioma determinado, llame a Number2Text con el argumento especial «help». En el ejemplo siguiente, supongamos que su configuración regional está establecida en «en-US», entonces la lista de prefijos disponibles para «en-US» se mostrará a través de un 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")

Temas relacionados

Servicio ScriptForge.Platform