ScriptForge.Region-tjenesten

Indhold

# Tjenesten ScriptForge.Region

Tjenesten Region tilbyder en samling af egenskaber og metoder til at håndtere lokale og regions-relaterede aspekter af programmering, for eksempel:

- Adgang til lokalitet og regionsafhængige indstillinger såsom talformatering, valuta og tidszoner.

- Konvertering af tidszoner og beregning af sommertids-forskydninger (DST = Daylight Saving Time).

- Omdannelse af tal til tekst på et hvilket som helst understøttet sprog.

## Definitioner

### Lokalitet eller region

En streng, der kombinerer et sprog og et land i formatet "la-CO" (language-COUNTRY = sprog-LAND). Sprogdelen er udtrykt med 2 eller 3 små bogstaver efterfulgt af en bindestreg og 2 store bogstaver, der repræsenterer landet.

For eksempel svarer "en-US" til det engelske sprog i USA; "fr-BE svarer til det franske sprog i Belgien, og så videre.

I nogle situationer er den fulde lokalitet ikke påkrævet, og kun sproget eller landet kan angives.

De fleste egenskaber og metoder accepterer en lokalitet som argument. Hvis ingen lokalitet er angivet, så bruges lokaliteten fra brugerfladen, som er defineret i OfficeLocale-egenskaben fra Platform-tjenesten.

### Tidszone

En streng i formatet "Region/By", for eksempel "Europe/Berlin" eller et tidszone-ID som "UTC" eller "GMT-8:00". Se wikisiden List of tz database time zones for en liste over mulige tidszone-navne og -ID'er.

Hvis en ugyldig tidszonestreng gives til en af metoderne i tjenesten Region, vil det ikke resultere i en afviklingsfejl. I stedet vil metoder som UTCDateTime og UTCNow returnere den aktuelle dato og klokkeslæt fra operativsystemet.

Tidsforskydningen mellem tidszonen og Greenwich Mean Time (GMT) er udtrykt i minutter.

Sommertid (DST = Daylight Saving Time) er en yderligere forskydning.

Tidsforskydningerne for tidszonen og DST kan være positive eller negative.

## Kald af tjenesten

Før du bruger Region-tjenesten skal biblioteket ScriptForge være indlæst eller importeret:

• Basic-makroer kræver, at biblioteket ScriptForge indlæses med følgende udtryk:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Python-scripts kræver import af scriptforge-modulet:
from scriptforge import CreateScriptService

De følgende eksempler i Basic og Python opretter instanser af Region-tjenesten og tilgår egenskaben Country (land).

##### I Basic

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

##### I Python

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

## Egenskaber

Alle egenskaberne opført herunder accepterer et locale-argument (lokalitet), givet som en streng. Nogle egenskaber kræver at dette argument er i formatet "la-CO" (language-COUNTRY = sprog-LAND), mens andre accepterer "la" eller "CO" som input.

Navn | Skrivebeskyttet | Type | Lokalitet | Beskrivelse
--- | --- | --- | --- | ---
Country | Ja | String | "la‑CO" "CO" | Returnerer det landenavn på engelsk, som svarer til en given region.
Currency | Ja | String | "la-CO" "CO" | Returnerer ISO 4217-valutakoden for den angivne region.
DatePatterns | Ja | Streng-array | "la-CO" | Returnerer et array af strenge, med 0 som første indeks, der indeholder dato-genkendelsesmønstrene for den angivne region.
DateSeparator | Ja | String | "la-CO" | Returnerer datoskilletegnet brugt i den givne region.
DayAbbrevNames | Ja | Streng-array | "la-CO" "la" | Returnerer et array af strenge med 0 som første indeks, der indeholder listen over forkortede ugedagsnavne på det angivne sprog.
DayNames | Ja | Streng-array | "la-CO" "la" | Returnerer et array af strenge med 0 som første indeks, der indeholder listen over ugedagsnavne på det angivne sprog.
DayNarrowNames | Ja | Streng-array | "la-CO" "la" | Returnerer et array af strenge med 0 som første indeks, der indeholder listen over ugedagenes initialer på det angivne sprog.
DecimalPoint | Ja | String | "la-CO" | Returnerer decimaltegnet brugt i decimaltal (kommatal) i den angivne region.
Language | Ja | String | "la-CO" "la" | Returnerer navnet på sproget, på engelsk, for den angivne region.
ListSeparator | Ja | String | "la-CO" | Returnerer listeskilletegnet brugt i den angivne region.
MonthAbbrevNames | Ja | Streng-array | "la-CO" "la" | Returnerer et array af strenge, med 0 som første indeks, der indeholder listen over forkortede månedsnavne på det angivne sprog.
MonthNames | Ja | Streng-array | "la-CO" "la" | Returnerer et array af strenge, med 0 som første indeks, der indeholder listen over månedsnavne på det angivne sprog.
MonthNarrowNames | Ja | Streng-array | "la-CO" "la" | Returnerer et array af strenge, med 0 som første indeks, der indeholder initialerne for månedsnavne på det angivne sprog.
ThousandSeparator | Ja | String | "la-CO" | Returnerer tusindtalsskilletegnet brugt i tal i den angivne region.
TimeSeparator | Ja | String | "la-CO" | Returnerer skilletegnet brugt til at formatere klokkeslæt i den angivne region.

Liste over metoder i tjenesten Region
DSTOffset LocalDateTime | Number2Text TimeZoneOffset | UTCDateTime UTCNow

## DSTOffset

Beregner den ekstra tidsforskydning fra sommertid (DST = Daylight Saving Time) i minutter, som gælder for en given region og tidszone.

### Syntaks:

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

### Parametre:

localdatetime: Den lokale dato og klokkeslæt udtrykt som en dato.

timezone: Tidszonen som tidsforskydningen skal beregnes for.

locale: Lokaliteten der angiver landet, som tidsforskydningen vil blive beregnet for, givet i formatet "la-CO" (language-COUNTRY = sprog-LAND) eller formatet "CO". Standardværdien er lokaliteten defineret i OfficeLocale-egenskaben fra Platform-tjenesten.

### Eksempel:

##### I Basic

          ' Beregner tidsforskydningen gældende i tidszonen "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 (minutter)
          aDateTime = DateSerial(2022, 1, 1) + TimeSerial(16, 0, 0)
          offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 0 (minutter)

##### I Python

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

## LocalDateTime

Beregner lokal dato og klokkeslæt fra en UTC-dato og -klokkeslæt.

### Syntaks:

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

### Parametre:

utcdatetime: UTC-dato og -klokkeslæt, udtrykt som et datoobjekt (Date).

timezone: Den tidszone, som den lokale tid vil blive beregnet for.

locale: Lokaliteten der angiver det land, som den lokale tid skal beregnes for, givet i formatet "la-CO" (language-COUNTRY = sprog-LAND) eller formatet "CO". Standardværdien er lokaliteten defineret i OfficeLocale-egenskaben fra Platform-tjenesten.

### Eksempel:

##### I Basic

          ' 6. juni 2022 kl. 10:30:45 (brugt her som UTC-tid)
          Dim UTCTime As Date, localTime As Date
          UTCTime = DateSerial(2022, 6, 23) + TimeSerial(10, 30, 45)
          ' Beregner den lokale tid i Sao Paulo, Brasilien
          ' 6. juni 2022 kl. 07:30:45
          localTime = oRegion.LocalDateTime(UTCTime, "America/Sao_Paulo", "BR")

##### I Python

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

## Number2Text

Konverterer tal og pengeværdier til skrevet tekst for et hvilket som helst af de aktuelt understøttede sprog.

Du finder en liste over alle understøttede sprog i API-referencen XNumberText Interface.

### Syntaks:

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

### Parametre:

number: Tallet som skal konverteres til skreven tekst. Det kan angives som en talværdi eller som en tekststreng. Når der angives en streng, kan den indledes med et præfiks, der giver information om, hvordan tallene skal skrives. Det er også muligt at inkludere ISO 4217-valutakoder. Se eksemplerne herunder for mere information.

locale: Lokaliteten som definerer det sprog, som tallet skal konverteres til, angivet i format "la-CO" (language-COUNTRY = sprog-LAND) eller "la". Standardværdien er lokaliteten defineret i OfficeLocale-egenskaben fra Platform-tjenesten.

### Eksempel:

##### I Basic

          ' Returnerer "et hundrede og fem"
          Dim numText As String
          numText = oRegion.Number2Text(105, "da-DK")
          ' Returnerer: "to komma toogfyrre"
          numText = oRegion.Number2Text(2.42, "da-DK")
          ' Returnerer: "femogtyve euro ti cent"; læg mærke til valutasymbolet "EUR"
          numText = oRegion.Number2Text("EUR 25.10", "da-DK")
          ' Returnerer: "femtende"; læg mærke til præfikset "ordinal"
          numText = oRegion.Number2Text("ordinal 15", "da-DK")

##### I Python

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

For at få en liste over alle understøttede præfikser for et givet sprog, kald Number2Text med det specielle argument "help". I eksemplet nedenfor, antag at din lokalitet er sat til "en-UD", så vil listen af tilgængelige præfikser for "en-US" blive vist med 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

Den første linje i beskedboksen har ikke et præfiks, hvilket betyder, at det er standardformatet. De efterfølgende linjer inkluderer præfikset og nogle eksempler på tal, der bruger dets format.

Hvert sprog har sit eget sæt af understøttede præfikser. Antallet af tilgængelige præfikser kan variere fra sprog til sprog.

For at få listen over præfikser for et specifikt sprog eller lokalitet, kan det angives som det andet argument til Number2Text. Eksemplet nedenfor viser de tilgængelige præfikser for for lokaliteten "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

Returnerer forskydningen mellem GMT og den givne tidszone og lokalitet i minutter.

### Syntaks:

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

### Parametre:

timezone: Den tidszone, som tidsforskydningen til GMT skal beregnes for.

locale: Lokaliteten der angiver landet, som tidsforskydningen vil blive beregnet for, givet i formatet "la-CO" (language-COUNTRY = sprog-LAND) eller formatet "CO". Standardværdien er lokaliteten defineret i OfficeLocale-egenskaben fra Platform-tjenesten.

### Eksempel:

##### I Basic

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

##### I Python

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

## UTCDateTime

Returnerer UTC-datoen og -klokkeslættet ud fra en given lokal dato og klokkeslæt i en tidszone.

### Syntaks:

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

### Parametre:

localdatetime: Den lokale dato og klokkeslæt i en specifik tidszone, udtrykt som en dato (Date).

timezone: Den tidszone, som argumentet localdatetime blev angivet for.

locale: Lokaliteten der angiver landet, som localdatetime gjaldt for, givet i formatet "la-CO" (language-COUNTRY = sprog-LAND) eller formatet "CO". Standardværdien er lokaliteten defineret i OfficeLocale-egenskaben fra Platform-tjenesten.

### Eksempel:

##### I Basic

          ' Dato/klokkeslæt i Berlin, 23. juni 2022 kl. 14:30:00
          Dim localDT As Date, utcTime As Date
          localDT = DateSerial(2022, 6, 23) + TimeSerial(14, 30, 0)
          ' UTC-dato/klokkeslæt er 23. juni 2022 kl. 12:30:00
          utcTime = oRegion.UTCDateTime(localDT, "Europe/Berlin", "DE")

##### I Python

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

## UTCNow

Returnerer den aktuelle UTC-dato og -klokkeslæt givet en tidszone og en lokalitet.

Denne metode bruger den aktuelle dato og klokkeslæt for dit operativsystem til at beregne UTC-tiden.

### Syntaks:

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

### Parametre:

timezone: Den tidszone, som den aktuelle UTC-tid skal beregnes for.

locale: Lokaliteten der angiver landet, som den aktuelle UTC-tid skal beregnes for, givet i formatet "la-CO" (language-COUNTRY = sprog-LAND) eller formatet "CO". Standardværdien er lokaliteten defineret i OfficeLocale-egenskaben fra Platform-tjenesten.

### Eksempel:

##### I Basic

          ' Antag at operativsystem-tidspunktet er 23. juni 2022 kl. 10:42:00
          ' Hvis computeren er i Europe/Berlin, så er UTC-tiden 23. juni 2022 kl. 08:42:00
          Dim utcTime As Date
          utcTime = oRegion.UTCNow("Europe/Berlin", "DE")

##### I Python

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

Relaterede emner

Tjenesten ScriptForge.Platform