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:

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.

note

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.

warning

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.

note

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


Invocare il servizio

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

note

• 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.

tip

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.

note

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

Sosteneteci!