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.

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

Servizio ScriptForge.Platform