Contenuto

# Servizio ScriptForge.Region

Il servizio Region fornisce una raccolta di proprietà e metodi per gestire aspetti della programmazione legati alle impostazioni locali e regionali, come ad esempio:

- Accesso alle impostazioni locali e dipendenti dalla regione corrente come la formattazione dei numeri, delle valute e i fusi orari.

- Conversione dei fusi orari e calcolo degli scostamenti dell'ora legale (DST).

- Trasformazione dei numeri in testi in qualsiasi delle lingue supportate.

## Definizioni

### Locale o Regione

Una stringa che combina una lingua e un paese nel formato "li-PA". La parte relativa alla lingua è espressa con 2 o 3 caratteri minuscoli seguiti da un trattino e 2 caratteri maiuscoli che rappresentano il paese.

Per esempio, "en-US" corrisponde alla lingua inglese degli Stati Uniti; "fr-BE" corrisponde alla lingua francese del Belgio e così via.

In alcune situazioni non è necessario indicare l'intero locale e può essere specificata solo la lingua o il paese.

La maggior parte delle proprietà e dei metodi accetta un locale come argomento. Se non è specificato il locale, viene usato quello dell'interfaccia utente, che è definito nella proprietà OfficeLocale del servizio Platform.

### Fuso orario

Una stringa nel formato "Regione/Città" come "Europe/Berlin", o l'ID di un fuso orario come "UTC" o "GMT-8:00". Fare riferimento alla pagina List of tz database and timezones di Wikipedia contenente l'elenco di tutti i nomi e gli ID possibili per i fusi orari.

L'indicazione per il fuso orario di una stringa non valida in qualunque metodo del servizio Region non comporterà un errore in fase di esecuzione. Piuttosto, metodi come UTCDateTime e UTCNow restituiranno la data e l'ora corrente del sistema operativo.

Lo scostamento dell'ora tra i fusi orari e l'ora del meridiano di Greenwich (GMT) è espresso in minuti.

Quello dell'ora legale (DST) è uno scostamento aggiuntivo.

Gli scostamenti del fuso orario e dell'ora legale (DST) possono essere positivi o negativi.

## Invocazione del servizio

Prima di usare il servizio Region è necessario caricare o importare le librerie ScriptForge:

• Le macro in Basic richiedono il caricamento della libreria ScriptForge usando la seguente istruzione:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Gli script in Python richiedono un'importazione dal modulo scriptforge:
from scriptforge import CreateScriptService

Gli esempi sottostanti in Basic e Python istanziano il servizio Region e accedono alla proprietà Country.

##### In Basic

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

##### In Python

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

## Proprietà

Tutte le proprietà sotto elencate accettano un argomento locale, indicato in formato stringa. Alcune proprietà richiedono che questo argomento sia nel formato "li-PA", mentre altri possono ricevere come input "li" o "PA".

Nome | Sola lettura | Tipo | Impostazione locale | Descrizione
--- | --- | --- | --- | ---
Country | Sì | String | "la‑CO" "CO" | Restituisce il nome inglese del paese corrispondente alla regione indicata.
Currency | Sì | String | "la-CO" "CO" | Restituisce il codice ISO 4217 della valuta della regione specificata.
DatePatterns | Sì | Matrice di stringhe | "la-CO" | Restituisce una matrice di stringhe, con indice a partire da zero, contenente i modelli accettati per le date della regione specificata.
DateSeparator | Sì | String | "la-CO" | Restituisce il separatore usato nelle date per la regione indicata.
DayAbbrevNames | Sì | Matrice di stringhe | "la-CO" "la" | Restituisce una matrice di stringhe, con indice a partire da zero, contenente l'elenco delle abbreviazioni dei nomi dei giorni della settimana nella lingua specificata.
DayNames | Sì | Matrice di stringhe | "la-CO" "la" | Restituisce una matrice di stringhe, con indice a partire da zero, contenente l'elenco dei nomi dei giorni della settimana nella lingua specificata.
DayNarrowNames | Sì | Matrice di stringhe | "la-CO" "la" | Restituisce una matrice di stringhe, con indice a partire da zero, contenente l'elenco delle iniziali dei nomi dei giorni della settimana nella lingua specificata.
DecimalPoint | Sì | String | "la-CO" | Restituisce il separatore dei decimali usato nei numeri nella regione specificata.
Language | Sì | String | "la-CO" "la" | Restituisce il nome della lingua, in inglese, della regione specificata.
ListSeparator | Sì | String | "la-CO" | Restituisce l'elenco dei separatori usati nella regione specificata.
MonthAbbrevNames | Sì | Matrice di stringhe | "la-CO" "la" | Restituisce una matrice di stringhe, con indice a partire da zero, contenente l'elenco delle abbreviazioni dei nomi dei mesi nella lingua specificata.
MonthNames | Sì | Matrice di stringhe | "la-CO" "la" | Restituisce una matrice di stringhe, con indice a partire da zero, contenente l'elenco dei nomi dei mesi nella lingua specificata.
MonthNarrowNames | Sì | Matrice di stringhe | "la-CO" "la" | Restituisce una matrice di stringhe, con indice a partire da zero, contenente l'elenco delle iniziali dei nomi dei mesi nella lingua specificata.
ThousandSeparator | Sì | String | "la-CO" | Restituisce il separatore delle migliaia usato nei numeri nella regione specificata.
TimeSeparator | Sì | String | "la-CO" | Restituisce il separatore usato per formattare gli orari nella regione specificata.

Elenco dei metodi del servizio Region
DSTOffset LocalDateTime | Number2Text TimeZoneOffset | UTCDateTime UTCNow

## DSTOffset

Calcola lo scostamento dovuto all'ora legale (DST), in minuti, applicabile alla regione e fuso orario indicati.

### Sintassi:

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

### Parametri:

localdatetime: la data e l'ora locale espresse in formato data.

timezone: il fuso orario di cui calcolare lo scostamento.

locale: il locale che specifica il paese per cui calcolare lo scostamento, indicato in uno dei formati "li-PA" o "PA". Il valore predefinito è il locale impostato nella proprietà OfficeLocale del servizio Platform.

### Esempio:

##### In Basic

          ' Calcola lo scostamento applicabile per il fuso orario "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 (minuti)
          aDateTime = DateSerial(2022, 1, 1) + TimeSerial(16, 0, 0)
          offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 0 (minuti)

##### In Python

          import datetime
          aDateTime = datetime.datetime(2022, 7, 1, 16, 0, 0)
          offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 60 (minuti)
          aDateTime = datetime.datetime(2022, 1, 1, 16, 0, 0)
          offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 0 (minuti)

## LocalDateTime

Calcola la data e ora locali a partire da data e ora UTC.

### Sintassi:

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

### Parametri:

utcdatetime: la data e ora UTC, espressa usando un oggetto date.

timezone: il fuso orario per cui calcolare l'ora locale.

locale: il locale che specifica il paese per cui calcolare l'ora locale, indicato in uno dei formati "li-PA" o "PA". Il valore predefinito è il locale impostato nella proprietà OfficeLocale del servizio Platform.

### Esempio:

##### In Basic

          ' 6 giugno 2022 alle 10:30:45 (qui usato come ora UTC)
          Dim UTCTime As Date, localTime As Date
          UTCTime = DateSerial(2022, 6, 23) + TimeSerial(10, 30, 45)
          ' Calcola l'ora locale di San Paolo, Brasile
          ' 6 giugno 2022 alle 07:30:45
          localTime = oRegion.LocalDateTime(UTCTime, "America/Sao_Paulo", "BR")

##### In Python

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

## Number2Text

Converte numeri e valori monetari in testo scritto per qualsiasi delle lingue attualmente supportate.

Per un elenco di tutte le lingue supportate visitate la pagina XNumberText Interface della guida di riferimento per le API.

### Sintassi:

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

### Parametri:

number: il numero da convertire in testo scritto. Può essere fornito sia come tipo numerico, sia come stringa. Quando viene indicato come stringa, può essere preceduto da un prefisso che indica come il numero dovrebbe essere scritto. È possibile includere anche i codici ISO 4217 per le valute. Vedere gli esempi seguenti per maggiori informazioni.

locale: il locale che definisce la lingua in cui il numero deve essere convertito, indicato in uno dei formati "li-PA" o "PA". Il valore predefinito è il locale impostato nella proprietà OfficeLocale del servizio Platform.

### Esempio:

##### In Basic

          ' Restituisce "centocinque"
          Dim numText As String
          numText = oRegion.Number2Text(105, "en-US")
          ' Restituisce: "due virgola quarantadue"
          numText = oRegion.Number2Text(2.42, "en-US")
          ' Restituisce: "venticinque euro e dieci centesimi", da notare il simbolo della valuta "EUR"
          numText = oRegion.Number2Text("EUR 25.10", "en-US")
          ' Restituisce: "quindicesimo"; da notare il prefisso "ordinal"
          numText = oRegion.Number2Text("ordinal 15", "it-IT")

##### In Python

          numText = oRegion.Number2Text(105, "it-IT")
          numText = oRegion.Number2Text(2.42, "it-IT")
          numText = oRegion.Number2Text("EUR 25.10", "it-IT")
          numText = oRegion.Number2Text("ordinal 15", "it-IT")

Per ottenere un elenco di tutti i prefissi supportati per una determinata lingua, chiamare Number2Text con l'argomento speciale "help". Nell'esempio seguente, si presuppone che locale sia impostato a "en-US", quindi l'elenco dei prefissi disponibili per "en-US" sarà visualizzato da 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 prima riga nella finestra di messaggio non ha un prefisso, ciò significa che quello è il formato standard. Le righe successive includono i prefisso e alcuni numeri di esempio che fanno uso del relativo formato.

Ogni lingua ha il suo insieme di prefissi supportati. Il numero dei prefissi disponibili può variare da lingua a lingua.

Per ottenere un elenco dei prefissi di una determinata lingua o impostazione locale, è possibile specificarla come secondo argomento di Number2Text. L'esempio seguente mostra i prefissi disponibili per l'impostazione locale "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

Restituisce lo scostamento in minuti tra l'ora GMT e il fuso orario e le impostazioni locali indicate.

### Sintassi:

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

### Parametri:

timezone: il fuso orario di cui calcolare lo scostamento rispetto all'ora GMT.

locale: il locale che specifica il paese per cui calcolare lo scostamento, indicato in uno dei formati "li-PA" o "PA". Il valore predefinito è il locale impostato nella proprietà OfficeLocale del servizio Platform.

### Esempio:

##### In Basic

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

##### In Python

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

## UTCDateTime

Restituisce la data e l'ora UTC considerando la data e l'ora indicate in formato locale e con riferimento al fuso orario.

### Sintassi:

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

### Parametri:

localdatetime: la data e ora locale nel fuso orario specificato indicate in formato date.

timezone: il fuso orario per il quale è stato fornito l'argomento localdatetime.

locale: il locale che specifica il paese per cui è stato indicato l'argomento localdatetime, espresso in uno dei formati "li-PA" o "PA". Il valore predefinito è il locale impostato nella proprietà OfficeLocale del servizio Platform.

### Esempio:

##### In Basic

          ' Date/Time in Berlin, 23 giugno 2022 alle 14:30:00
          Dim localDT As Date, utcTime As Date
          localDT = DateSerial(2022, 6, 23) + TimeSerial(14, 30, 0)
          ' la data/ora in UTC è June 23, 2022 at 12:30:00
          utcTime = oRegion.UTCDateTime(localDT, "Europe/Berlin", "DE")

##### In Python

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

## UTCNow

Restituisce data e ora UTC correnti, in base al fuso orario e locale indicati.

Questo metodo usa la data e ora correnti del sistema operativo per calcolare l'ora UTC.

### Sintassi:

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

### Parametri:

timezone: il fuso orario per cui calcolare l'ora UTC corrente.

locale: il locale che specifica il paese per cui calcolare l'ora UTC corrente, indicato in uno dei formati "li-PA" o "PA". Il valore predefinito è il locale impostato nella proprietà OfficeLocale del servizio Platform.

### Esempio:

##### In Basic

          ' Supponendo che l'ora del sistema operativo sia 22 giugno 2022 alle 10:42:00
          ' Se il computer si trova in Europe/Berlin, l'ora UTC sarà 23 giugno 2022 alle 08:42:00
          Dim utcTime As Date
          utcTime = oRegion.UTCNow("Europe/Berlin", "DE")

##### In Python

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

Argomenti correlati

Servizio ScriptForge.Platform