1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
|
<?xml version="1.0" encoding="UTF-8"?>
<helpdocument version="1.0">
<!--
* This file is part of the LibreOffice project.
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/.
*
-->
<meta>
<topic id="SF_Region" indexer="include" status="PUBLISH">
<title id="tit" xml-lang="en-US">ScriptForge.Region service</title>
<filename>/text/sbasic/shared/03/sf_region.xhp</filename>
</topic>
</meta>
<body>
<section id="ScriptForge-sf_region">
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id501600788079651">
<bookmark_value>Region service</bookmark_value>
</bookmark>
</section>
<section id="abstract">
<h1 id="bm_id681600788076499"><variable id="RegionService"><link href="text/sbasic/shared/03/sf_region.xhp"><literal>ScriptForge</literal>.<literal>Region</literal> service</link></variable></h1>
<paragraph role="paragraph" id="par_id181600788076612">The <literal>Region</literal> service provides a collection of properties and methods to handle locale and region-related aspects of programming, such as:</paragraph>
<list type="unordered">
<listitem>
<paragraph id="par_id301600788076785" role="listitem">Accessing locale and region-dependent settings such as number formatting, currency and timezones.</paragraph>
</listitem>
<listitem>
<paragraph id="par_id1001600788076848" role="listitem">Converting timezones and calculate Daylight Saving Time (DST) offsets.</paragraph>
</listitem>
<listitem>
<paragraph id="par_id67160078807676" role="listitem">Transforming numbers into text in any supported language.</paragraph>
</listitem>
</list>
</section>
<h2 id="hd_id851656012844548">Definitions</h2>
<h3 id="hd_id421656012886648">Locale or Region</h3>
<paragraph role="paragraph" id="par_id191656012908838">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.</paragraph>
<paragraph role="paragraph" id="par_id431656013368415">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.</paragraph>
<paragraph role="paragraph" id="par_id981656013623018">On some situations the full locale is not required and only the language or country may be specified.</paragraph>
<note id="par_id261656013132204">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 <link href="text/sbasic/shared/03/sf_platform.xhp#bm_id111614901524769"><literal>OfficeLocale</literal></link> property of the <literal>Platform</literal> service.</note>
<h3 id="hd_id51656013825718">Timezone</h3>
<paragraph role="paragraph" id="par_id541656013854150">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 <link href="https://wikipedia.org/wiki/List_of_tz_database_time_zones">List of tz database timezones</link> for a list of possible timezone names and IDs.</paragraph>
<warning id="par_id981656078937577">Providing an invalid timezone string to any of the methods in the <literal>Region</literal> service will not result in a runtime error. Instead, methods as <literal>UTCDateTime</literal> and <literal>UTCNow</literal> will return the current operating system date and time.</warning>
<paragraph role="paragraph" id="par_id611656014040098">The time offset between the timezone and the Greenwich Meridian Time (GMT) is expressed in minutes.</paragraph>
<paragraph role="paragraph" id="par_id121656014053670">The Daylight Saving Time (DST) is an additional offset.</paragraph>
<note id="par_id591656014140929">The timezone and DST offsets may be positive or negative.</note>
<h2 id="hd_id281600788076359">Service invocation</h2>
<paragraph role="paragraph" id="par_id141609955500101">Before using the <literal>Region</literal> service the <literal>ScriptForge</literal> library needs to be loaded or imported:</paragraph>
<embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#importLibs"/>
<paragraph role="paragraph" id="par_id321614902851541">The examples below in Basic and Python instantiate the <literal>Region</literal> service and access the <literal>Country</literal> property.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id851600788076202">GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")</paragraph>
<paragraph role="bascode" localize="false" id="bas_id1001600788076254">Dim oRegion As Variant</paragraph>
<paragraph role="bascode" localize="false" id="bas_id721600788076288">oRegion = CreateScriptService("Region")</paragraph>
<paragraph role="bascode" id="bas_id791600788431935">MsgBox oRegion.Country("en-US") ' United States</paragraph>
</bascode>
<embed href="text/sbasic/shared/00000003.xhp#In_Python"/>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id631626695710139">from scriptforge import CreateScriptService</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id981626695710433">oRregion = CreateScriptService("Region")</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id311626695710851">bas = CreateScriptService("Basic")</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id391626695711082">bas.MsgBox(oRegion.Country("en-US"))</paragraph>
</pycode>
<bookmark xml-lang="en-US" branch="index" localize="false" id="bm_id11161490152686">
<bookmark_value>Region service;Country</bookmark_value>
<bookmark_value>Region service;Currency</bookmark_value>
<bookmark_value>Region service;DatePatterns</bookmark_value>
<bookmark_value>Region service;DateSeparator</bookmark_value>
<bookmark_value>Region service;DayAbbrevNames</bookmark_value>
<bookmark_value>Region service;DayNames</bookmark_value>
<bookmark_value>Region service;DayNarrowNames</bookmark_value>
<bookmark_value>Region service;DecimalPoint</bookmark_value>
<bookmark_value>Region service;Language</bookmark_value>
<bookmark_value>Region service;ListSeparator</bookmark_value>
<bookmark_value>Region service;MonthAbbrevNames</bookmark_value>
<bookmark_value>Region service;MonthNames</bookmark_value>
<bookmark_value>Region service;MonthNarrowNames</bookmark_value>
<bookmark_value>Region service;ThousandSeparator</bookmark_value>
<bookmark_value>Region service;TimeSeparator</bookmark_value>
</bookmark>
<h2 id="hd_id711600788076834">Properties</h2>
<paragraph role="paragraph" id="par_id601656018689690">All properties listed below accept a <literal>locale</literal> 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.</paragraph>
<section id="properties_toc">
<table id="tab_id701600788076583">
<tablerow>
<tablecell>
<paragraph id="par_id461600788076917" role="tablehead">Name</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id221600788076591" role="tablehead">Readonly</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id761600788076328" role="tablehead">Type</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id131656330679679" role="tablehead">Locale</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id67160078807636" role="tablehead">Description</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id491600788076621" role="tablecontent" localize="false">Country</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id311600788076756" role="tablecontent">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id831600788076785" role="tablecontent" localize="false">String</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id411656330757666" role="tablecontent" localize="false">"la‑CO"<br/>"CO"</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id441600788076826" role="tablecontent">Returns the country name in English corresponding to a given region.</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id941600788076595" role="tablecontent" localize="false">Currency</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id49160078807654" role="tablecontent">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id961600788076376" role="tablecontent" localize="false">String</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id131656330815396" role="tablecontent" localize="false">"la-CO"<br/>"CO"</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id81600788076419" role="tablecontent">Returns the ISO 4217 currency code of the specified region.</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id721600788076638" role="tablecontent" localize="false">DatePatterns</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id711600788076534" role="tablecontent">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id911600788076842" role="tablecontent">String array</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id131656330815199" role="tablecontent" localize="false">"la-CO"</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id541600788076645" role="tablecontent">Returns a zero-based array of strings containing the date acceptance patterns for the specified region.</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id961600788076890" role="tablecontent" localize="false">DateSeparator</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id891600788076190" role="tablecontent">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id761600788076562" role="tablecontent" localize="false">String</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id131656330809635" role="tablecontent" localize="false">"la-CO"</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id91600788076674" role="tablecontent">Returns the date separator used in the given region.</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id831633021719246" localize="false" role="tablecontent">DayAbbrevNames</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id561633021747014" role="tablecontent">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id201633021748566" role="tablecontent">String array</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id131656330815320" role="tablecontent" localize="false">"la-CO"<br/>"la"</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id831633021745014" role="tablecontent">Returns a zero-based array of strings containing the list of abbreviated weekday names in the specified language.</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id831633021716585" localize="false" role="tablecontent">DayNames</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id561633021747209" role="tablecontent">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id201633021748322" role="tablecontent">String array</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id131656330815767" role="tablecontent" localize="false">"la-CO"<br/>"la"</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id831633021748865" role="tablecontent">Returns a zero-based array of strings containing the list of weekday names in the specified language.</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id831633021719135" localize="false" role="tablecontent">DayNarrowNames</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id561633021747903" role="tablecontent">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id201633021748455" role="tablecontent">String array</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id131656330819641" role="tablecontent" localize="false">"la-CO"<br/>"la"</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id831633021747711" role="tablecontent">Returns a zero-based array of strings containing the list of the initials of weekday names in the specified language.</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id831633021710186" localize="false" role="tablecontent">DecimalPoint</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id561633021748013" role="tablecontent">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id201633021749655" localize="false" role="tablecontent">String</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id131656330816830" role="tablecontent" localize="false">"la-CO"</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id831633021749297" role="tablecontent">Returns the decimal separator used in numbers in the specified region.</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id831633021719022" localize="false" role="tablecontent">Language</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id561633021743188" role="tablecontent">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id201633021743058" localize="false" role="tablecontent">String</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id131656330816697" role="tablecontent" localize="false">"la-CO"<br/>"la"</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id831633021749018" role="tablecontent">Returns the name of the language, in English, of the specified region.</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id951600788076443" role="tablecontent" localize="false">ListSeparator</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id391600788076253" role="tablecontent">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id381600788076799" role="tablecontent" localize="false">String</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id131656330816642" role="tablecontent" localize="false">"la-CO"</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id21600788076541" role="tablecontent">Returns the list separator used in the specified region.</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id831633021710156" localize="false" role="tablecontent">MonthAbbrevNames</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id561633021706513" role="tablecontent">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id201633021746335" role="tablecontent">String array</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id131656330814533" role="tablecontent" localize="false">"la-CO"<br/>"la"</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id831633021741117" role="tablecontent">Returns a zero-based array of strings containing the list of abbreviated month names in the specified language.</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id41600788076936" role="tablecontent" localize="false">MonthNames</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id211600788076138" role="tablecontent">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id221600788076518" role="tablecontent">String array</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id131656330817644" role="tablecontent" localize="false">"la-CO"<br/>"la"</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id521600788076371" role="tablecontent">Returns a zero-based array of strings containing the list of month names in the specified language.</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id161600788076362" role="tablecontent" localize="false">MonthNarrowNames</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id21600788076758" role="tablecontent">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id871600788076196" role="tablecontent">String array</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id131656330812262" role="tablecontent" localize="false">"la-CO"<br/>"la"</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id781600788076694" role="tablecontent">Returns a zero-based array of strings containing the list of the initials of month names in the specified language.</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id471600788076885" role="tablecontent" localize="false">ThousandSeparator</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id261600788076841" role="tablecontent">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id661600788076636" role="tablecontent" localize="false">String</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id131656330844830" role="tablecontent" localize="false">"la-CO"</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id116007880767507" role="tablecontent">Returns the thousands separator used in numbers in the specified region.</paragraph>
</tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id221600789141781" role="tablecontent" localize="false">TimeSeparator</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id531600789141795" role="tablecontent">Yes</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id561600789141282" role="tablecontent" localize="false">String</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id131656330817766" role="tablecontent" localize="false">"la-CO"</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id301600789141619" role="tablecontent">Returns the separator used to format times in the specified region.</paragraph>
</tablecell>
</tablerow>
</table>
</section>
<section id="methods_toc">
<table id="tab_id901611086279902">
<tablerow>
<tablecell colspan="3"><paragraph id="par_id651606319520519" role="tablehead">List of Methods in the Region Service</paragraph></tablecell>
</tablerow>
<tablerow>
<tablecell>
<paragraph id="par_id761611086279902" role="tablecontent" localize="false">
<link href="text/sbasic/shared/03/sf_region.xhp#DSTOffset">DSTOffset</link><br/>
<link href="text/sbasic/shared/03/sf_region.xhp#LocalDateTime">LocalDateTime</link><br/>
</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id141611086279902" role="tablecontent" localize="false">
<link href="text/sbasic/shared/03/sf_region.xhp#Number2Text">Number2Text</link><br/>
<link href="text/sbasic/shared/03/sf_region.xhp#TimeZoneOffset">TimeZoneOffset</link><br/>
</paragraph>
</tablecell>
<tablecell>
<paragraph id="par_id761611086279903" role="tablecontent" localize="false">
<link href="text/sbasic/shared/03/sf_region.xhp#UTCDateTime">UTCDateTime</link><br/>
<link href="text/sbasic/shared/03/sf_region.xhp#UTCNow">UTCNow</link><br/>
</paragraph>
</tablecell>
</tablerow>
</table>
</section>
<section id="DSTOffset">
<comment> DSTOffset ---------------------------------------------------------------------------------------------- </comment>
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919969187">
<bookmark_value>Region service;DSTOffset</bookmark_value>
</bookmark>
<h2 id="hd_id201589199698020" localize="false">DSTOffset</h2>
<paragraph role="paragraph" id="par_id71621894830071">Computes the additional Daylight Saving Time (DST) offset, in minutes, that is applicable to a given region and timezone.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
<paragraph role="paragraph" localize="false" id="par_id591621897208117">
<input>svc.DSTOffset(localdatetime: date, timezone: str, opt locale: str): int</input>
</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functparameters"/>
<paragraph role="paragraph" id="par_id401621896675880"><emph>localdatetime</emph>: the local date and time expressed as a date.</paragraph>
<paragraph role="paragraph" id="par_id401621896675125"><emph>timezone</emph>: the timezone for which the offset will be calculated.</paragraph>
<paragraph role="paragraph" id="par_id401621896675963"><emph>locale</emph>: 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 <link href="text/sbasic/shared/03/sf_platform.xhp#bm_id111614901524769"><literal>OfficeLocale</literal></link> property of the <literal>Platform</literal> service.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
<bascode>
<paragraph role="bascode" id="bas_id531656022497519">' Calculates the offset applicable in the "America/Los_Angeles" timezone</paragraph>
<paragraph role="bascode" localize="false" id="bas_id201656782497415">Dim aDateTime As Date, offset As Integer</paragraph>
<paragraph role="bascode" localize="false" id="bas_id201656022497919">aDateTime = DateSerial(2022, 7, 1) + TimeSerial(16, 0, 0)</paragraph>
<paragraph role="bascode" id="bas_id801656022498143">offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 60 (minutes)</paragraph>
<paragraph role="bascode" localize="false" id="bas_id601656022498128">aDateTime = DateSerial(2022, 1, 1) + TimeSerial(16, 0, 0)</paragraph>
<paragraph role="bascode" id="bas_id831656022498543">offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 0 (minutes)</paragraph>
</bascode>
<embed href="text/sbasic/shared/00000003.xhp#In_Python"/>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id761621898860952">import datetime</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id861621898933001">aDateTime = datetime.datetime(2022, 7, 1, 16, 0, 0)</paragraph>
<paragraph role="pycode" id="pyc_id871621898933281">offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 60 (minutes)</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id861621898934287">aDateTime = datetime.datetime(2022, 1, 1, 16, 0, 0)</paragraph>
<paragraph role="pycode" id="pyc_id871621898934141">offset = oRegion.DSTOffset(aDateTime, "America/Los_Angeles", "US") ' 0 (minutes)</paragraph>
</pycode>
</section>
<section id="LocalDateTime">
<comment> LocalDateTime ------------------------------------------------------------------------------------------ </comment>
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919969630">
<bookmark_value>Region service;LocalDateTime</bookmark_value>
</bookmark>
<h2 id="hd_id201589199698124" localize="false">LocalDateTime</h2>
<paragraph role="paragraph" id="par_id71621894832058">Computes the local date and time from a UTC date and time.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
<paragraph role="paragraph" localize="false" id="par_id591621897208785">
<input>svc.LocalDateTime(utcdatetime: date, timezone: str, opt locale: str): date</input>
</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functparameters"/>
<paragraph role="paragraph" id="par_id401621896674716"><emph>utcdatetime</emph>: the UTC date and time, expressed using a date object.</paragraph>
<paragraph role="paragraph" id="par_id401621896675449"><emph>timezone</emph>: the timezone for which the local time will be calculated.</paragraph>
<paragraph role="paragraph" id="par_id401621896675193"><emph>locale</emph>: 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 <link href="text/sbasic/shared/03/sf_platform.xhp#bm_id111614901524769"><literal>OfficeLocale</literal></link> property of the <literal>Platform</literal> service.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
<bascode>
<paragraph role="bascode" id="bas_id201656022497017">' June 6th, 2022 at 10:30:45 (used here as UTC time)</paragraph>
<paragraph role="bascode" localize="false" id="bas_id711656454548454">Dim UTCTime As Date, localTime As Date</paragraph>
<paragraph role="bascode" localize="false" id="bas_id803696022498143">UTCTime = DateSerial(2022, 6, 23) + TimeSerial(10, 30, 45)</paragraph>
<paragraph role="bascode" id="bas_id531656022497121">' Calculates local time in Sao Paulo, Brazil</paragraph>
<paragraph role="bascode" id="bas_id601656022498318">' June 6th, 2022 at 07:30:45</paragraph>
<paragraph role="bascode" localize="false" id="bas_id830696022498543">localTime = oRegion.LocalDateTime(UTCTime, "America/Sao_Paulo", "BR")</paragraph>
</bascode>
<embed href="text/sbasic/shared/00000003.xhp#In_Python"/>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id761621898833352">import datetime</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id861621898933128">utcTime = datetime.datetime(2022, 6, 23, 10, 30, 45)</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id871621898933337">localTime = oRegion.LocalDateTime(utcTime, "America/Sao_Paulo", "BR")</paragraph>
</pycode>
</section>
<section id="Number2Text">
<comment> Number2Text ------------------------------------------------------------------------------------------- </comment>
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919966650">
<bookmark_value>Region service;Number2Text</bookmark_value>
</bookmark>
<h2 id="hd_id201589199698374" localize="false">Number2Text</h2>
<paragraph role="paragraph" id="par_id71621894832089">Converts numbers and monetary values into written text for any of the currently supported languages.</paragraph>
<tip id="par_id971656026551328">For a list of all supported languages visit the <link href="https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1linguistic2_1_1XNumberText.html">XNumberText Interface</link> API reference.</tip>
<embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
<paragraph role="paragraph" localize="false" id="par_id591621897208441">
<input>svc.Number2Text(number: any, opt locale: str): str</input>
</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functparameters"/>
<paragraph role="paragraph" id="par_id401621896675306"><emph>number</emph>: 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.</paragraph>
<paragraph role="paragraph" id="par_id401621896675412"><emph>locale</emph>: 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 <link href="text/sbasic/shared/03/sf_platform.xhp#bm_id111614901524769"><literal>OfficeLocale</literal></link> property of the <literal>Platform</literal> service.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
<bascode>
<paragraph role="bascode" id="bas_id301656027173020">' Returns "one hundred five"</paragraph>
<paragraph role="bascode" localize="false" id="bas_id851656454602974">Dim numText As String</paragraph>
<paragraph role="bascode" id="bas_id531656022496631">numText = oRegion.Number2Text(105, "en-US")</paragraph>
<paragraph role="bascode" id="bas_id771656027217144">' Returns: "two point four two"</paragraph>
<paragraph role="bascode" id="bas_id201656022493367">numText = oRegion.Number2Text(2.42, "en-US")</paragraph>
<paragraph role="bascode" id="bas_id281656027262234">' Returns: "twenty-five euro and ten cents" Notice the "EUR" currency symbol</paragraph>
<paragraph role="bascode" id="bas_id201656022497171">numText = oRegion.Number2Text("EUR 25.10", "en-US")</paragraph>
<paragraph role="bascode" id="bas_id981656027330132">' Returns: "fifteenth"; Notice the "ordinal" prefix</paragraph>
<paragraph role="bascode" id="bas_id841656027330394">numText = oRegion.Number2Text("ordinal 15", "en-US")</paragraph>
</bascode>
<embed href="text/sbasic/shared/00000003.xhp#In_Python"/>
<pycode>
<paragraph role="pycode" id="pyc_id401656027481473">numText = oRegion.Number2Text(105, "en-US")</paragraph>
<paragraph role="pycode" id="pyc_id781656027481769">numText = oRegion.Number2Text(2.42, "en-US")</paragraph>
<paragraph role="pycode" id="pyc_id951656027482096">numText = oRegion.Number2Text("EUR 25.10", "en-US")</paragraph>
<paragraph role="pycode" id="pyc_id231656027482425">numText = oRegion.Number2Text("ordinal 15", "en-US")</paragraph>
</pycode>
<paragraph role="paragraph" id="par_id801656027524051">To get a list of all supported prefixes in a given language, call <literal>Number2Text</literal> 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 <literal>MsgBox</literal>:</paragraph>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id851656027713735">prefixes = oRegion.Number2Text("help")</paragraph>
<paragraph role="bascode" localize="false" id="bas_id716560277139601">MsgBox prefixes</paragraph>
<paragraph role="bascode" localize="false" id="bas_id216560277123601">' one, two, three</paragraph>
<paragraph role="bascode" localize="false" id="bas_id361656027712711">' ordinal: first, second, third</paragraph>
<paragraph role="bascode" localize="false" id="bas_id891656027712920">' ordinal-number: 1st, 2nd, 3rd</paragraph>
<paragraph role="bascode" localize="false" id="bas_id611656027713104">' year: nineteen ninety-nine, two thousand, two thousand one</paragraph>
<paragraph role="bascode" localize="false" id="bas_id861656027713288">' currency (for example, USD): two U.S. dollars and fifty cents</paragraph>
<paragraph role="bascode" localize="false" id="bas_id841656027713503">' money USD: two and 50/100 U.S. dollars</paragraph>
</bascode>
<paragraph role="paragraph" id="par_id781656027840633">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.</paragraph>
<note id="par_id781656028528520">Each language has its own set of supported prefixes. The number of available prefixes may vary from language to language.</note>
<paragraph role="paragraph" id="par_id531663849363398">To get the list of prefixes for a specific language or locale, it can be specified as the second argument in <literal>Number2Text</literal>. The example below shows the available prefixes available for the "pt-BR" locale:</paragraph>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id301663849799013">prefixes = oRegion.Number2Text("help", "pt-BR")</paragraph>
<paragraph role="bascode" localize="false" id="bas_id801663849799462">MsgBox prefixes</paragraph>
<paragraph role="bascode" localize="false" id="bas_id931663849708619">' um, dois, três</paragraph>
<paragraph role="bascode" localize="false" id="bas_id416638497808923">' feminine: uma, duas, três</paragraph>
<paragraph role="bascode" localize="false" id="bas_id371663849709114">' masculine: um, dois, três</paragraph>
<paragraph role="bascode" localize="false" id="bas_id701663849709307">' ordinal-feminine: primeira, segunda, terceira</paragraph>
<paragraph role="bascode" localize="false" id="bas_id411663849709530">' ordinal-masculine: primeiro, segundo, terceiro</paragraph>
<paragraph role="bascode" localize="false" id="bas_id611663849709803">' ordinal-number-feminine: 1.ª, 2.ª, 3.ª</paragraph>
<paragraph role="bascode" localize="false" id="bas_id831663849710011">' ordinal-number-masculine: 1.º, 2.º, 3.º</paragraph>
</bascode>
</section>
<section id="TimeZoneOffset">
<comment> TimeZoneOffset ----------------------------------------------------------------------------------------- </comment>
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919966017">
<bookmark_value>Region service;TimeZoneOffset</bookmark_value>
</bookmark>
<h2 id="hd_id201589199691085" localize="false">TimeZoneOffset</h2>
<paragraph role="paragraph" id="par_id71621894832117">Returns the offset between GMT and the given timezone and locale, in minutes.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
<paragraph role="paragraph" localize="false" id="par_id591621897203066">
<input>svc.TimeZoneOffset(timezone: str, opt locale: str): int</input>
</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functparameters"/>
<paragraph role="paragraph" id="par_id401621896675018"><emph>timezone</emph>: the timezone for which the offset to the GMT will be calculated.</paragraph>
<paragraph role="paragraph" id="par_id401621896675691"><emph>locale</emph>: 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 <link href="text/sbasic/shared/03/sf_platform.xhp#bm_id111614901524769"><literal>OfficeLocale</literal></link> property of the <literal>Platform</literal> service.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
<bascode>
<paragraph role="bascode" localize="false" id="bas_id101656454730797">Dim offset As Integer</paragraph>
<paragraph role="bascode" localize="false" id="bas_id916560675890495">offset = oRegion.TimeZoneOffset("America/New_York", "US") ' -300</paragraph>
<paragraph role="bascode" localize="false" id="bas_id211656075890806">offset = oRegion.TimeZoneOffset("Europe/Berlin", "DE") ' 60</paragraph>
</bascode>
<embed href="text/sbasic/shared/00000003.xhp#In_Python"/>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id1001656076044293">offset = oRegion.TimeZoneOffset("America/New_York", "US") # -300</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id5015656076044605">offset = oRegion.TimeZoneOffset("Europe/Berlin", "DE") # 60</paragraph>
</pycode>
</section>
<section id="UTCDateTime">
<comment> UTCDateTime ----------------------------------------------------------------------------------------- </comment>
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919943207">
<bookmark_value>Region service;UTCDateTime</bookmark_value>
</bookmark>
<h2 id="hd_id201589199691808" localize="false">UTCDateTime</h2>
<paragraph role="paragraph" id="par_id71621894864217">Returns the UTC date and time considering a given local date and time in a timezone.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
<paragraph role="paragraph" localize="false" id="par_id591621897202644">
<input>svc.UTCDateTime(localdatetime: date, timezone: str, opt locale: str): date</input>
</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functparameters"/>
<paragraph role="paragraph" id="par_id401621896674748"><emph>localdatetime</emph>: the local date and time in a specific timezone expressed as a date.</paragraph>
<paragraph role="paragraph" id="par_id401621896675739"><emph>timezone</emph>: the timezone for which the <literal>localdatetime</literal> argument was given.</paragraph>
<paragraph role="paragraph" id="par_id401621896675550"><emph>locale</emph>: the locale specifying the country for which the <literal>localdatetime</literal> argument was given, expressed either in "la-CO" or "CO" formats. The default value is the locale defined in the <link href="text/sbasic/shared/03/sf_platform.xhp#bm_id111614901524769"><literal>OfficeLocale</literal></link> property of the <literal>Platform</literal> service.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
<bascode>
<paragraph role="bascode" id="bas_id861656077547861">' Date/Time in Berlin, June 23, 2022 at 14:30:00</paragraph>
<paragraph role="bascode" localize="false" id="bas_id771656454767976">Dim localDT As Date, utcTime As Date</paragraph>
<paragraph role="bascode" localize="false" id="bas_id911656077521797">localDT = DateSerial(2022, 6, 23) + TimeSerial(14, 30, 0)</paragraph>
<paragraph role="bascode" id="bas_id731656077523173">' The UTC date/time is June 23, 2022 at 12:30:00</paragraph>
<paragraph role="bascode" localize="false" id="bas_id1001656077527477">utcTime = oRegion.UTCDateTime(localDT, "Europe/Berlin", "DE")</paragraph>
</bascode>
<embed href="text/sbasic/shared/00000003.xhp#In_Python"/>
<pycode>
<paragraph role="pycode" localize="false" id="pyc_id361656077667354">import datetime</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id901656077667666">localDT = datetime.datetime(2022, 6, 23, 14, 30, 0)</paragraph>
<paragraph role="pycode" localize="false" id="pyc_id521656077682826">utcTime = oRegion.UTCDateTime(localDT, "Europe/Berlin", "DE")</paragraph>
</pycode>
</section>
<section id="UTCNow">
<comment> UTCNow ----------------------------------------------------------------------------------------- </comment>
<bookmark xml-lang="en-US" localize="false" branch="index" id="bm_id92158919939587">
<bookmark_value>Region service;UTCNow</bookmark_value>
</bookmark>
<h2 id="hd_id201589199694336" localize="false">UTCNow</h2>
<paragraph role="paragraph" id="par_id71621894835287">Returns the current UTC date and time, given a timezone and locale.</paragraph>
<paragraph role="paragraph" id="par_id491656078254442">This method uses the current date and time of your operating system to calculate the UTC time.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
<paragraph role="paragraph" localize="false" id="par_id591621897201935">
<input>svc.UTCNow(timezone: str, opt locale: str): date</input>
</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functparameters"/>
<paragraph role="paragraph" id="par_id401621896673318"><emph>timezone</emph>: the timezone for which the current UTC time will be calculated.</paragraph>
<paragraph role="paragraph" id="par_id401621896674831"><emph>locale</emph>: 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 <link href="text/sbasic/shared/03/sf_platform.xhp#bm_id111614901524769"><literal>OfficeLocale</literal></link> property of the <literal>Platform</literal> service.</paragraph>
<embed href="text/sbasic/shared/00000003.xhp#functexample"/>
<embed href="text/sbasic/shared/00000003.xhp#In_Basic"/>
<bascode>
<paragraph role="bascode" id="bas_id861656078128374">' Suppose the operating system time is June 23rd, 2022 at 10:42:00</paragraph>
<paragraph role="bascode" id="bas_id691656078180784">' If the computer is in Europe/Berlin, then UTC time is June 23rd, 2022 at 08:42:00</paragraph>
<paragraph role="bascode" localize="false" id="bas_id351656454814865">Dim utcTime As Date</paragraph>
<paragraph role="bascode" localize="false" id="bas_id881656078243397">utcTime = oRegion.UTCNow("Europe/Berlin", "DE")</paragraph>
</bascode>
<embed href="text/sbasic/shared/00000003.xhp#In_Python"/>
<pycode>
<paragraph role="pycode" id="pyc_id821656078645252">utcTime = oRegion.UTCNow("Europe/Berlin", "DE")</paragraph>
</pycode>
</section>
<section id="relatedtopics">
<embed href="text/sbasic/shared/03/sf_platform.xhp#PlatformService"/>
</section>
</body>
</helpdocument>
|
