ScriptForge.Region service

Περιεχόμενα

# Υπηρεσία ScriptForge.Region

Η υπηρεσία Region (Περιοχή) παρέχει μια συλλογή ιδιοτήτων και μεθόδων για τον χειρισμό πτυχών προγραμματισμού που σχετίζονται με τις τοπικές ρυθμίσεις και την περιοχή, όπως:

- Πρόσβαση σε τοπικές ρυθμίσεις και ρυθμίσεις που εξαρτώνται από την περιοχή, όπως η μορφοποίηση αριθμών, το νόμισμα και οι ζώνες χρόνου.

- Μετατροπή ζωνών χρόνου και υπολογισμός αλλαγών θερινής ώρας (DST).

- Μετατροπή αριθμών σε κείμενο σε οποιαδήποτε υποστηριζόμενη γλώσσα.

## Ορισμοί

### Τοπικές ρυθμίσεις ή περιοχή

Μια συμβολοσειρά που συνδυάζει μια γλώσσα και μια χώρα στη μορφή "la-CO". Το τμήμα της γλώσσας εκφράζεται με 2 ή 3 πεζούς χαρακτήρες ακολουθούμενους από μια παύλα και 2 κεφαλαίους χαρακτήρες που αντιπροσωπεύουν τη χώρα.

Για παράδειγμα, το "en-US" αντιστοιχεί στην αγγλική γλώσσα στις Ηνωμένες Πολιτείες. Το "fr-BE" αντιστοιχεί στη γαλλική γλώσσα στο Βέλγιο, και ούτω καθεξής.

Σε ορισμένες περιπτώσεις δεν απαιτείται η πλήρης τοπική ρύθμιση και μπορεί να καθοριστεί μόνο η γλώσσα ή η χώρα.

Οι περισσότερες ιδιότητες και μέθοδοι δέχονται μια τοπική ρύθμιση ως όρισμα. Εάν δεν έχει καθοριστεί τοπική ρύθμιση, τότε χρησιμοποιείται η τοπική ρύθμιση διεπαφής χρήστη, η οποία ορίζεται στην ιδιότητα OfficeLocaleτης υπηρεσίας Platform.

### Ζώνη χρόνου

A string in the format "Region/City" such as "Europe/Berlin", or a timezone ID such as "UTC" or "GMT-8:00". Refer to the wiki page List of tz database timezones for a list of possible timezone names and IDs.

Η παροχή μιας άκυρης συμβολοσειράς ζώνης χρόνου σε οποιαδήποτε από τις μεθόδους στην υπηρεσία Region (Περιοχή) δεν θα οδηγήσει σε σφάλμα χρόνου εκτέλεσης. Αντίθετα, μέθοδοι όπως UTCDateTime και UTCNow θα επιστρέψουν την τρέχουσα ημερομηνία και χρόνο του λειτουργικού συστήματος.

Η μετατόπιση χρόνου μεταξύ της ζώνης χρόνου και του χρόνου μεσημβρινού του Γκρίνουιτς (GMT) εκφράζεται σε λεπτά.

Η θερινή ώρα (DST) είναι μια επιπλέον αλλαγή.

Οι αλλαγές ζώνης χρόνου και θερινής ώρας μπορεί να είναι θετικές ή αρνητικές.

## Κλήση υπηρεσίας

Πριν χρησιμοποιήσετε την υπηρεσία Region, πρέπει να φορτωθεί ή να εισαχθεί η βιβλιοθήκη ScriptForge:

• Οι μακροεντολές Basic απαιτούν τη φόρτωση της βιβλιοθήκης ScriptForge χρησιμοποιώντας την ακόλουθη πρόταση:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Τα σενάρια Python απαιτούν εισαγωγή από την ενότητα scriptforge:
από το scriptforge import CreateScriptService

Τα παρακάτω παραδείγματα σε Basic και Python δημιουργούν την υπηρεσία Region και έχουν πρόσβαση στην ιδιότητα Country.

##### Σε Basic

        GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
        Dim oRegion As Variant
        oRegion = CreateScriptService("Region")
        MsgBox oRegion.Country("en-US") ' Ηνωμένες Πολιτείες

##### Σε Python

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

## Ιδιότητες

Όλες οι ιδιότητες που αναφέρονται παρακάτω αποδέχονται ένα όρισμα locale, το οποίο παρέχεται ως συμβολοσειρά. Ορισμένες ιδιότητες απαιτούν αυτό το όρισμα να έχει τη μορφή "la-CO", ενώ άλλες μπορεί να λαμβάνουν "la" ή "CO" ως είσοδο.

Όνομα | Μόνο για ανάγνωση | Τύπος | Τοπική ρύθμιση | Περιγραφή
--- | --- | --- | --- | ---
Country | Ναι | String | "la‑CO" "CO" | Επιστρέφει το όνομα της χώρας στα αγγλικά που αντιστοιχεί σε μια δεδομένη περιοχή.
Currency | Ναι | String | "la-CO" "CO" | Επιστρέφει τον κωδικό νομίσματος ISO 4217 της καθορισμένης περιοχής.
DatePatterns | Ναι | Πίνακας συμβολοσειρών | "la-CO" | Επιστρέφει έναν πίνακα συμβολοσειρών με βάση το μηδέν που περιέχει τα μοτίβα αποδοχής ημερομηνίας για την καθορισμένη περιοχή.
DateSeparator | Ναι | String | "la-CO" | Επιστρέφει το διαχωριστικό ημερομηνιών που χρησιμοποιείται στη δεδομένη περιοχή.
DayAbbrevNames | Ναι | Πίνακας συμβολοσειρών | "la-CO" "la" | Επιστρέφει έναν πίνακα συμβολοσειρών με βάση το μηδέν που περιέχει τον κατάλογο των συντομευμένων ονομάτων καθημερινών ημερών στην καθορισμένη γλώσσα.
DayNames | Ναι | Πίνακας συμβολοσειρών | "la-CO" "la" | Returns a zero-based array of strings containing the list of weekday names in the specified language.
DayNarrowNames | Yes | String array | "la-CO" "la" | Returns a zero-based array of strings containing the list of the initials of weekday names in the specified language.
DecimalPoint | Yes | String | "la-CO" | Returns the decimal separator used in numbers in the specified region.
Language | Yes | String | "la-CO" "la" | Returns the name of the language, in English, of the specified region.
ListSeparator | Yes | String | "la-CO" | Returns the list separator used in the specified region.
MonthAbbrevNames | Yes | String array | "la-CO" "la" | Returns a zero-based array of strings containing the list of abbreviated month names in the specified language.
MonthNames | Yes | String array | "la-CO" "la" | Returns a zero-based array of strings containing the list of month names in the specified language.
MonthNarrowNames | Yes | String array | "la-CO" "la" | Returns a zero-based array of strings containing the list of the initials of month names in the specified language.
ThousandSeparator | Yes | String | "la-CO" | Returns the thousands separator used in numbers in the specified region.
TimeSeparator | Yes | String | "la-CO" | Returns the separator used to format times in the specified region.

List of Methods in the Region Service
DSTOffset LocalDateTime | Number2Text TimeZoneOffset | UTCDateTime UTCNow

## DSTOffset

Computes the additional Daylight Saving Time (DST) offset, in minutes, that is applicable to a given region and timezone.

### Σύνταξη:

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

### Παράμετροι:

localdatetime: the local date and time expressed as a date.

timezone: the timezone for which the offset will be calculated.

locale: the locale specifying the country for which the offset will be calculated, given either in "la-CO" or "CO" formats. The default value is the locale defined in the OfficeLocale property of the Platform service.

### Παράδειγμα:

##### Σε Basic

          ' Calculates the offset applicable in the "America/Los_Angeles" timezone
          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 (minutes)
          aDateTime = DateSerial(2022, 1, 1) + TimeSerial(16, 0, 0)
          offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 0 (minutes)

##### Σε Python

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

## LocalDateTime

Computes the local date and time from a UTC date and time.

### Σύνταξη:

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

### Παράμετροι:

utcdatetime: the UTC date and time, expressed using a date object.

timezone: the timezone for which the local time will be calculated.

locale: the locale specifying the country for which the local time will be calculated, given either in "la-CO" or "CO" formats. The default value is the locale defined in the OfficeLocale property of the Platform service.

### Παράδειγμα:

##### Σε Basic

          ' June 6th, 2022 at 10:30:45 (used here as UTC time)
          Dim UTCTime As Date, localTime As Date
          UTCTime = DateSerial(2022, 6, 23) + TimeSerial(10, 30, 45)
          ' Calculates local time in Sao Paulo, Brazil
          ' June 6th, 2022 at 07:30:45
          localTime = oRegion.LocalDateTime(UTCTime, "America/Sao_Paulo", "BR")

##### Σε Python

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

## Number2Text

Converts numbers and monetary values into written text for any of the currently supported languages.

For a list of all supported languages visit the XNumberText Interface API reference.

### Σύνταξη:

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

### Παράμετροι:

number: the number to be converted into written text. It can be provided either as a numeric type or as a string. When a string is provided, it can be preceded by a prefix informing how the numbers should be written. It is also possible to include ISO 4217 currency codes. See examples below for more information.

locale: the locale defining the language into which the number will be converted to, given either in "la-CO" or "la" formats. The default value is the locale defined in the OfficeLocale property of the Platform service.

### Παράδειγμα:

##### Σε Basic

          ' Returns "one hundred five"
          Dim numText As String
          numText = oRegion.Number2Text(105, "en-US")
          ' Returns: "two point four two"
          numText = oRegion.Number2Text(2.42, "en-US")
          ' Returns: "twenty-five euro and ten cents" Notice the "EUR" currency symbol
          numText = oRegion.Number2Text("EUR 25.10", "en-US")
          ' Returns: "fifteenth"; Notice the "ordinal" prefix
          numText = oRegion.Number2Text("ordinal 15", "en-US")

##### Σε 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

The first line in the message box does not have a prefix, which means that it is the standard format. The subsequent lines include the prefix and some examples of numbers using its format.

Each language has its own set of supported prefixes. The number of available prefixes may vary from language to language.

To get the list of prefixes for a specific language or locale, it can be specified as the second argument in Number2Text. The example below shows the available prefixes available for the "pt-BR" locale:

          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

Returns the offset between GMT and the given timezone and locale, in minutes.

### Σύνταξη:

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

### Παράμετροι:

timezone: the timezone for which the offset to the GMT will be calculated.

locale: the locale specifying the country for which the offset will be calculated, given either in "la-CO" or "CO" formats. The default value is the locale defined in the OfficeLocale property of the Platform service.

### Παράδειγμα:

##### Σε Basic

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

##### Σε Python

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

## UTCDateTime

Returns the UTC date and time considering a given local date and time in a timezone.

### Σύνταξη:

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

### Παράμετροι:

localdatetime: the local date and time in a specific timezone expressed as a date.

timezone: the timezone for which the localdatetime argument was given.

locale: the locale specifying the country for which the localdatetime argument was given, expressed either in "la-CO" or "CO" formats. The default value is the locale defined in the OfficeLocale property of the Platform service.

### Παράδειγμα:

##### Σε Basic

          ' Date/Time in Berlin, June 23, 2022 at 14:30:00
          Dim localDT As Date, utcTime As Date
          localDT = DateSerial(2022, 6, 23) + TimeSerial(14, 30, 0)
          ' The UTC date/time is June 23, 2022 at 12:30:00
          utcTime = oRegion.UTCDateTime(localDT, "Europe/Berlin", "DE")

##### Σε Python

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

## UTCNow

Returns the current UTC date and time, given a timezone and locale.

This method uses the current date and time of your operating system to calculate the UTC time.

### Σύνταξη:

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

### Παράμετροι:

timezone: the timezone for which the current UTC time will be calculated.

locale: the locale specifying the country for which the current UTC time will be calculated, given either in "la-CO" or "CO" formats. The default value is the locale defined in the OfficeLocale property of the Platform service.

### Παράδειγμα:

##### Σε Basic

          ' Suppose the operating system time is June 23rd, 2022 at 10:42:00
          ' If the computer is in Europe/Berlin, then UTC time is June 23rd, 2022 at 08:42:00
          Dim utcTime As Date
          utcTime = oRegion.UTCNow("Europe/Berlin", "DE")

##### Σε Python

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

Σχετικά θέματα

ΥπηρεσίαScriptForge.Platform