+ + + + ScriptForge.Region service + /text/sbasic/shared/03/sf_region.xhp + + + +

+ + Region service + +

ScriptForge.Region service

+ The Region service provides a collection of properties and methods to handle locale and region-related aspects of programming, such as: + + + Accessing locale and region-dependent settings such as number formatting, currency and timezones. + + + Converting timezones and calculate Daylight Saving Time (DST) offsets. + + + Transforming numbers into text in any supported language. + + +

+ +

Definitions

Locale or Region

+ A string combining a language and a country in the format "la-CO". The language part is expressed with 2 or 3 lowercase characters followed by a dash and 2 uppercase characters representing the country. + For instance, "en-US" corresponds to the English language in the United States; "fr-BE" corresponds to the French language in Belgium, and so forth. + On some situations the full locale is not required and only the language or country may be specified. + Most properties and methods accept a locale as argument. If no locale is specified, then the user-interface locale is used, which is defined in the OfficeLocale property of the Platform service. +

Timezone

+ 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 and timezones for a list of possible timezone names and IDs. + Providing an invalid timezone string to any of the methods in the Region service will not result in a runtime error. Instead, methods as UTCDateTime and UTCNow will return the current operating system date and time. + The time offset between the timezone and the Greenwich Meridian Time (GMT) is expressed in minutes. + The Daylight Saving Time (DST) is an additional offset. + The timezone and DST offsets may be positive or negative. + +

Service invocation

+ Before using the Region service the ScriptForge library needs to be loaded or imported: +

+ The examples below in Basic and Python instantiate the Region service and access the Country property. +

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

+ + from scriptforge import CreateScriptService + oRregion = CreateScriptService("Region") + bas = CreateScriptService("Basic") + bas.MsgBox(oRegion.Country("en-US")) + + + + Region service;Country + Region service;Currency + Region service;DatePatterns + Region service;DateSeparator + Region service;DayAbbrevNames + Region service;DayNames + Region service;DayNarrowNames + Region service;DecimalPoint + Region service;Language + Region service;ListSeparator + Region service;MonthAbbrevNames + Region service;MonthNames + Region service;MonthNarrowNames + Region service;ThousandSeparator + Region service;TimeSeparator + + +

Properties

+ All properties listed below accept a locale argument, provided as a string. Some properties require this argument to be in the format "la-CO", whereas others may receive "la" or "CO" as input. + + + + + Name + + + Readonly + + + Type + + + Locale + + + Description + + + + + Country + + + Yes + + + String + + + "la‑CO"
"CO" + + + Returns the country name in English corresponding to a given region. + + + + + Currency + + + Yes + + + String + + + "la-CO"
"CO" + + + Returns the ISO 4217 currency code of the specified region. + + + + + DatePatterns + + + Yes + + + String array + + + "la-CO" + + + Returns a zero-based array of strings containing the date acceptance patterns for the specified region. + + + + + DateSeparator + + + Yes + + + String + + + "la-CO" + + + Returns the date separator used in the given region. + + + + + DayAbbrevNames + + + Yes + + + String array + + + "la-CO"
"la" + + + Returns a zero-based array of strings containing the list of abbreviated weekday names in the specified language. + + + + + DayNames + + + Yes + + + String array + + + "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 ---------------------------------------------------------------------------------------------- + + Region service;DSTOffset + +

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

+ + ' 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) + +

+ + 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 ------------------------------------------------------------------------------------------ + + Region service;LocalDateTime + +

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

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

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

+ +

+ Number2Text ------------------------------------------------------------------------------------------- + + Region service;Number2Text + +

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

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

+ + 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, as shown in the example below: + + prefixes = oRegion.Number2Text("help") + MsgBox prefixes + ' Considering the "en-US" locale the message box will show the following text + ' 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. +

+ +

+ TimeZoneOffset ----------------------------------------------------------------------------------------- + + Region service;TimeZoneOffset + +

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

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

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

+ +

+ UTCDateTime ----------------------------------------------------------------------------------------- + + Region service;UTCDateTime + +

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

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

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

+ +

+ UTCNow ----------------------------------------------------------------------------------------- + + Region service;UTCNow + +

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

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

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

+ +