AllLangHelp_sbasic.mk | 2
source/text/sbasic/shared/03/lib_ScriptForge.xhp | 21 -
source/text/sbasic/shared/03/sf_array.xhp | 410 +++++++++++++++++++++++
source/text/sbasic/shared/03/sf_dictionary.xhp | 410 +++++++++++++++++++++++
4 files changed, 835 insertions(+), 8 deletions(-)
New commits:
commit 24db503333ae5193babbd5db33c0344ca0c5e3e1
Author: Alain Romedenne <libreoffici...@sfr.fr>
AuthorDate: Tue Nov 24 16:33:22 2020 +0100
Commit: Olivier Hallot <olivier.hal...@libreoffice.org>
CommitDate: Tue Dec 8 00:30:40 2020 +0100
ScriptForge library modules - WiP
+ Array module
+ Dictionary module
Change-Id: Ida2290005befb59f2b7c3699744ff49b32226e24
Reviewed-on: https://gerrit.libreoffice.org/c/help/+/106513
Tested-by: Jenkins
Tested-by: Jean-Pierre Ledure <j...@ledure.be>
Reviewed-by: Olivier Hallot <olivier.hal...@libreoffice.org>
diff --git a/AllLangHelp_sbasic.mk b/AllLangHelp_sbasic.mk
index 7423e9eba..71d311cdf 100644
--- a/AllLangHelp_sbasic.mk
+++ b/AllLangHelp_sbasic.mk
@@ -77,6 +77,8 @@ $(eval $(call gb_AllLangHelp_add_helpfiles,sbasic,\
helpcontent2/source/text/sbasic/shared/03/lib_importwiz \
helpcontent2/source/text/sbasic/shared/03/lib_script \
helpcontent2/source/text/sbasic/shared/03/lib_ScriptForge \
+ helpcontent2/source/text/sbasic/shared/03/sf_array \
+ helpcontent2/source/text/sbasic/shared/03/sf_dictionary \
helpcontent2/source/text/sbasic/shared/03/lib_schedule \
helpcontent2/source/text/sbasic/shared/03/lib_template \
helpcontent2/source/text/sbasic/shared/03/lib_wikieditor \
diff --git a/source/text/sbasic/shared/03/lib_ScriptForge.xhp
b/source/text/sbasic/shared/03/lib_ScriptForge.xhp
index c0f33a9c9..ef5f49d24 100644
--- a/source/text/sbasic/shared/03/lib_ScriptForge.xhp
+++ b/source/text/sbasic/shared/03/lib_ScriptForge.xhp
@@ -24,28 +24,33 @@
</section>
<note id="par_id901528999850603"><embedvar
href="text/sbasic/shared/00000003.xhp#basiclibrarynote" markup="keep"/><br/>
<item
type="literal">GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")</item></note>
-
+
<paragraph role="paragraph" id="par_id781606153472028">The described
modules and classes are invoked from user scripts as "Services". A generic
constructor of those services has been designed for that purpose:</paragraph>
<bascode>
<paragraph role="bascode"
id="bas_id201606153529501">[ScriptForge.][Services.]CreateScriptService("servicename"[,
arg0, Arg1, ...])</paragraph>
</bascode>
-
- <paragraph role="paragraph" id="par_id891606153700196">Services from
external libraries can registered with the
<literal>RegisterScriptServices(...)</literal> method in order to extend the
set of available services.</paragraph>
- <paragraph role="paragraph" id="par_id491606151060454">Array
Service</paragraph>
- <paragraph role="paragraph" id="par_id51606151111406">Dictionary class
Service</paragraph>
+ <paragraph role="paragraph" id="par_id891606153700196">Services from
external libraries can be registered with the
<literal>RegisterScriptServices(...)</literal> method in order to extend the
set of available services.</paragraph>
+
+ <section id="SF_InternalUse">
+ <warning id="par_id81606569891780">All <literal>ScriptForge</literal>
Basic routines or identifiers that are prefixed with an underscore "_"
character are reserved for internal use. They are not meant be used in Basic
macros.</warning>
+ </section>
+
+ <embed href="text/sbasic/shared/03/sf_array.xhp#abstract"/>
+ <embed href="text/sbasic/shared/03/sf_dictionary.xhp#abstract"/>
<paragraph role="paragraph" id="par_id341606151137912">Exception class
Service</paragraph>
<paragraph role="paragraph" id="par_id1001606151139039">FileSystem
Service</paragraph>
<paragraph role="paragraph" id="par_id511606151140972">L10n class
Service</paragraph>
<paragraph role="paragraph" id="par_id781606151141190">Platform
Service</paragraph>
- <paragraph role="paragraph" id="par_id821606151141382">Root class
Service</paragraph>
<paragraph role="paragraph" id="par_id771606151141575">Services class
Service</paragraph>
<paragraph role="paragraph" id="par_id671606151231848">Session
Service</paragraph>
<paragraph role="paragraph" id="par_id861606151242391">String
Service</paragraph>
- <paragraph role="paragraph" id="par_id791606151259895">TestStream class
Service</paragraph>
+ <paragraph role="paragraph" id="par_id791606151259895">TextStream class
Service</paragraph>
<paragraph role="paragraph" id="par_id951606151273072">Timer class
Service</paragraph>
<paragraph role="paragraph" id="par_id951606151282712">UI
Service</paragraph>
- <paragraph role="paragraph" id="par_id161606151295297">Utils
Service</paragraph>
+
+ <comment>Restricted use for SF_Root, SF_Utils</comment>
+ <note id="par_id851606569675843">Other <literal>ScriptForge</literal>
undescribed modules are restricted to this library internal use. Their content
is subject to change without notice.</note>
</body>
</helpdocument>
diff --git a/source/text/sbasic/shared/03/sf_array.xhp
b/source/text/sbasic/shared/03/sf_array.xhp
new file mode 100644
index 000000000..d37af6f49
--- /dev/null
+++ b/source/text/sbasic/shared/03/sf_array.xhp
@@ -0,0 +1,410 @@
+<?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_Dictionary" indexer="include" status="PUBLISH">
+ <title id="tit" xml-lang="en-US">ScriptForge.Dictionary service</title>
+ <filename>/text/sbasic/shared/03/sf_dictionary.xhp</filename>
+ </topic>
+</meta>
+<body>
+<section id="abstract">
+ <bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id261582733781987">
+ <bookmark_value>Dictionary service</bookmark_value>
+ <bookmark_value>API;DateTime</bookmark_value>
+ <bookmark_value>API;PropertyValue</bookmark_value>
+ </bookmark>
+
+ <h1 id="hd_id731582733781114"
xml-lang="en-US"><literal>ScriptForge</literal>.<literal>Dictionary</literal>
service</h1>
+
+ <paragraph role="paragraph" id="par_id891582884466217" xml-lang="en-US">A
dictionary is a collection of key-item pairs</paragraph>
+ <list type="unordered">
+ <listitem><paragraph id="par_id861582884516571" role="listitem"
xml-lang="en-US">The key is a case-insensitive string</paragraph></listitem>
+ <listitem><paragraph id="par_id531582884549542" role="listitem"
xml-lang="en-US">Items may be of any type</paragraph></listitem>
+ </list>
+</section>
+
+ <paragraph role="paragraph" id="par_id891582884593057" xml-lang="en-US">Keys
and items can be retrieved, counted, updated, and much more.</paragraph>
+ <paragraph role="tip" id="par_id971582884636922"
xml-lang="en-US">%PRODUCTNAME Basic <literal>Collection</literal> object does
not support the retrieval of the keys.
+ <br/>Additionally its items contain only primitive Basic data types such as
dates, text, numbers, and the like.</paragraph>
+
+ <h2 id="hd_id581582885621841" xml-lang="en-US">Service invocation</h2>
+
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id851582897798335">GlobalScope.BasicLibraries.loadLibrary("ScriptForge")</paragraph>
+ <paragraph role="bascode" localize="false" id="bas_id371582885621964">Dim
myDict As Variant</paragraph>
+ <paragraph role="bascode" localize="false" id="bas_id201582885621287">
myDict = CreateScriptService("Dictionary")</paragraph>
+ </bascode>
+
+ <paragraph role="paragraph" id="par_id71158288562139" xml-lang="en-US">It is
recommended to free resources after use:</paragraph>
+ <bascode>
+ <paragraph role="bascode" localize="false" id="bas_id721582885621540">Set
myDict = myDict.Dispose()</paragraph>
+ </bascode>
+
+ <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/>
+
+ <h2 id="hd_id351582885195476" xml-lang="en-US">Properties</h2>
+ <section id="Item">
+ <table id="tab_id971582885195582">
+ <tablerow>
+ <tablecell>
+ <paragraph id="par_id41582885195836" role="tablehead"
xml-lang="en-US">Name</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id31582885195372" role="tablehead"
xml-lang="en-US">Readonly</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id501582885895609" role="tablehead"
xml-lang="en-US">Argument</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id31582885195238" role="tablehead"
xml-lang="en-US">Type</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id931582885195131" role="tablehead"
xml-lang="en-US" >Description</paragraph>
+ </tablecell>
+ </tablerow>
+ <tablerow>
+ <tablecell>
+ <paragraph id="par_id97158288519551" role="tablecontent"
localize="false">Count</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id221582885195686" role="tablecontent"
xml-lang="en-US">Yes</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id851582885948589" role="tablecontent"
localize="false"></paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id371582885195525" role="tablecontent"
localize="false">Long</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id881582885195976" role="tablecontent"
xml-lang="en-US">The actual number of entries in the dictionary</paragraph>
+ </tablecell>
+ </tablerow>
+ <tablerow>
+ <tablecell>
+ <paragraph id="par_id7715828856553" role="tablecontent"
localize="false">Item</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id861582885655779" role="tablecontent"
xml-lang="en-US">Yes</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id621582885990445" role="tablecontent"
localize="false">Key As String</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id271582885655525" role="tablecontent"
localize="false">Variant</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id581582885655885" role="tablecontent"
xml-lang="en-US">The value of the item related to <literal>Key</literal><br
/><literal>Empty</literal> if not found</paragraph>
+ </tablecell>
+ </tablerow>
+ <tablerow>
+ <tablecell>
+ <paragraph id="par_id841582886030384" role="tablecontent"
localize="false">Items</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id441582886030118" role="tablecontent"
xml-lang="en-US">Yes</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id411582886030478" role="tablecontent"
localize="false"></paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id131582886030297" role="tablecontent"
xml-lang="en-US">Array of Variants</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id471582886030489" role="tablecontent"
xml-lang="en-US">The list of items as a one dimension array</paragraph>
+ </tablecell>
+ </tablerow>
+ <tablerow>
+ <tablecell>
+ <paragraph id="par_id231582886791351" role="tablecontent"
localize="false">Keys</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id971582886791838" role="tablecontent"
xml-lang="en-US">Yes</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id721582886791467" role="tablecontent"
localize="false"></paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id271582886791111" role="tablecontent"
xml-lang="en-US">Array of Strings</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id16158288679167" role="tablecontent"
xml-lang="en-US">The list of keys as a one dimension array</paragraph>
+ </tablecell>
+ </tablerow>
+ </table>
+ </section>
+
+ <paragraph role="tip" id="par_id461582886731495" xml-lang="en-US">The Keys
and Items properties return their respective contents, using an identical
ordering.
+ <br/>The order is unrelated to the creation sequence.</paragraph>
+
+ <h3 id="hd_id691582887572811" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functexample"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false" id="bas_id211582887012398">Dim
a As Variant, b As String</paragraph>
+ <paragraph role="bascode" localize="false" id="bas_id351582887179042">
a = myDict.Keys</paragraph>
+ <paragraph role="bascode" localize="false" id="bas_id251582887187534">
For Each b In a</paragraph>
+ <paragraph role="bascode" localize="false" id="bas_id121582887198799">
' ...</paragraph>
+ <paragraph role="bascode" localize="false" id="bas_id571606473148931">
Next b</paragraph>
+ </bascode>
+
+ <table id="tab_id891606472825856">
+ <tablerow>
+ <tablecell><paragraph id="par_id581606472825856" role="tablehead"
localize="false"></paragraph></tablecell>
+ <tablecell><paragraph id="par_id921606472825856"
role="tablehead">Methods</paragraph></tablecell>
+ <tablecell><paragraph id="par_id781606472825856" role="tablehead"
localize="false"></paragraph></tablecell>
+ </tablerow>
+ <tablerow>
+ <tablecell><paragraph id="par_id381606472825856" role="tablecontent">
+ <link href="text/sbasic/shared/03/sf_dictionary.xhp#Add" name="Add
method">Add</link><br/><br/>
+ <link href="text/sbasic/shared/03/sf_dictionary.xhp#ConvertToArray"
name="ConvertToArray method">ConvertToArray</link><br/>
+ <link href="text/sbasic/shared/03/sf_dictionary.xhp#ConvertToJson"
name="ConvertToJson method">ConvertToJson</link><br/>
+ <link
href="text/sbasic/shared/03/sf_dictionary.xhp#ConvertToPropertyValues"
name="ConvertToPropertyValues method">ConvertToPropertyValues</link>
+ </paragraph></tablecell>
+ <tablecell><paragraph id="par_id451606472825856" role="tablecontent">
+ <link href="text/sbasic/shared/03/sf_dictionary.xhp#Exists"
name="Exists method">Exists</link><br/><br/>
+ <link href="text/sbasic/shared/03/sf_dictionary.xhp#ImportFromJson"
name="ImportFromJson method">ImportFromJson</link><br/>
+ <link
href="text/sbasic/shared/03/sf_dictionary.xhp#ImportFromPropertyValues"
name="ImportFromPropertyValues method">ImportFromPropertyValues</link><br/>
+ <link href="text/sbasic/shared/03/sf_dictionary.xhp#Item"
name="Item method">Item</link>
+ </paragraph></tablecell>
+ <tablecell><paragraph id="par_id161606472825856" role="tablecontent">
+ <link href="text/sbasic/shared/03/sf_dictionary.xhp#Remove"
name="Remove method">Remove</link><br/>
+ <link href="text/sbasic/shared/03/sf_dictionary.xhp#RemoveAll"
name="RemoveAll method">RemoveAll</link><br/>
+ <link href="text/sbasic/shared/03/sf_dictionary.xhp#ReplaceItem"
name="ReplaceItem method">ReplaceItem</link><br/>
+ <link href="text/sbasic/shared/03/sf_dictionary.xhp#ReplaceKey"
name="ReplaceKey method">ReplaceKey</link>
+ </paragraph></tablecell>
+ </tablerow>
+ </table>
+
+ <section id="Add">
+ <comment> Add
--------------------------------------------------------------------------------------------------------------------------
</comment>
+ <bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id781582887670029">
+ <bookmark_value>Dictionary service;Add</bookmark_value>
+ </bookmark>
+ <h2 id="hd_id831582887670029" localize="false">Add</h2>
+ <paragraph role="paragraph" id="par_id831582887670029">Add a new
key-item pair into the dictionary. Returns <literal>True</literal> if
successful.</paragraph>
+ <h3 id="hd_id451582887670029" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functsyntax"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id731582887670029">myDict.Add(Key As String, Item As Variant) As
Boolean</paragraph>
+ </bascode>
+ <h3 id="hd_id821582887670030" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functparameters"/></h3>
+ <paragraph role="paragraph"
id="par_id341582887670030"><emph>Key</emph> : Not case-sensitive. Must not yet
exist in the dictionary, otherwise a <literal>DUPLICATEKEYERROR</literal> error
is generated. Spaces only generate a <literal>INVALIDKEYERROR</literal>
error.</paragraph>
+ <paragraph role="paragraph"
id="par_id401582887670030"><emph>Item</emph> : Any value, including an array, a
Basic object, a UNO object, a dictionary, ...</paragraph>
+ <h3 id="hd_id461582887670030" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functexample"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id191582887670030">Dim NewValue As Variant</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id391582887670030"> myDict.Add("NewKey", NewValue)</paragraph>
+ </bascode>
+ </section>
+
+ <section id="ConvertToArray">
+ <comment> ConvertToArray
--------------------------------------------------------------------------------------------------------------------------
</comment>
+ <bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id621582888424103">
+ <bookmark_value>Dictionary service;ConvertToArray</bookmark_value>
+ </bookmark>
+ <h2 id="hd_id211582888424104" localize="false">ConvertToArray</h2>
+ <paragraph role="paragraph" id="par_id81582888424104">Store the
content of the dictionary in a two-columns zero-based array. The key is stored
in the first column, the item is stored in the second column.
+ <br />The resulting array is empty when the dictionary is
empty.</paragraph>
+ <h3 id="hd_id201582888424104" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functsyntax"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id251582888424105">myDict.ConvertToArray() As Variant</paragraph>
+ </bascode>
+ </section>
+
+ <section id="ConvertToJson">
+ <comment> ConvertToJson
---------------------------------------------------------------------------------------------------------------------
</comment>
+ <bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id631601296836318">
+ <bookmark_value>Dictionary service;ConvertToJson</bookmark_value>
+ </bookmark>
+ <h2 id="hd_id851601296836224" localize="false">ConvertToJson</h2>
+ <paragraph role="paragraph" id="par_id831601296836981">Convert the
content of the dictionary to <link href="https://en.wikipedia.org/wiki/JSON";
name="JSON text">JSON (JavaScript Object Notation)</link> text.</paragraph>
+ <h3 id="hd_id261601297024828" xml-lang="en-US">Limitations</h3>
+ <paragraph role="paragraph" id="par_id401601297178073"
xml-lang="en-US">Allowed data types are: <literal>String</literal>,
<literal>Boolean</literal>, numbers, <literal>Null</literal> and
<literal>Empty</literal>. Arrays containing items of those types are allowed,
whatever their dimensions. Dates are converted into strings but not within
arrays where they are forbidden. Other data types are converted to their string
representation (cfr. SF_String.Represent).</paragraph>
+ <h3 id="hd_id551601296836572" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functsyntax"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id491601296836271">myDict.ConvertToJson([Indent As Variant]) As
String</paragraph>
+ </bascode>
+ <h3 id="hd_id1001601296836123" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functparameters"/></h3>
+ <paragraph role="paragraph" id="par_id8816012968362"><emph>Indent</emph>
: When <literal>Indent</literal> is a positive number or a text, JSON array
elements and object members are pretty-printed with that indent level. A
negative <literal>Indent</literal> value solely insert new lines.
<literal>Indent</literal> default value "" selects the most compact
representation. Using a positive integer for <literal>Indent</literal> indents
that many spaces per level. When <literal>Indent</literal> is a string, such as
<literal>Chr(9)</literal> or <literal>Tab(1)</literal>, the tab sign is used to
indent each level.</paragraph>
+ <h3 id="hd_id19160129683665" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functexample"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id671601298281962">myDict.Add("p0", 12.5)</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id851601298288784">myDict.Add("p1", "a string àé""ê")</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id201601298295976">myDict.Add("p2", DateSerial(2020,9,28))</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id951601298323286">myDict.Add("p3", True)</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id731601298329491">myDict.Add("p4", Array(1,2,3))</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id451601298336500">MsgBox a.ConvertToJson() ' {"p0": 12.5, "p1":
"a string \u00e0\u00e9\"\u00ea", "p2": "2020-09-28", "p3": true, "p4": [1, 2,
3]}</paragraph>
+ </bascode>
+ </section>
+
+ <section id="ConvertToPropertyValues">
+ <comment> ConvertToPropertyValues
-----------------------------------------------------------------------------------------------------------------------
</comment>
+ <bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id991582889470402">
+ <bookmark_value>Dictionary
service;ConvertToPropertyValues</bookmark_value>
+ </bookmark>
+ <h2 id="hd_id421582889470909"
localize="false">ConvertToPropertyValues</h2>
+ <paragraph role="paragraph" id="par_id151582889470596">Store the
content of the dictionary in an array of <literal>PropertyValues</literal>.
+ <br />Each entry in the array is a
<literal>com.sun.star.beans.PropertyValue</literal>. The key is stored in
<literal>Name</literal>, the item is stored in <literal>Value</literal>.
+ <br />If one of the items has a type <literal>Date</literal>, it is
converted to a <literal>com.sun.star.util.DateTime</literal> structure.
+ <br />If one of the items is an empty array, it is converted to
<literal>Null</literal>.
+ <br />The resulting array is empty when the dictionary is
empty.</paragraph>
+ <h3 id="hd_id841582889470464" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functsyntax"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id191582889470444">myDict.ConvertToPropertyValues() As
Variant</paragraph>
+ </bascode>
+ </section>
+
+ <section id="Exists">
+ <comment> Exists
--------------------------------------------------------------------------------------------------------------------------
</comment>
+ <bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id81582889812915">
+ <bookmark_value>Dictionary service;Exists</bookmark_value>
+ </bookmark>
+ <h2 id="hd_id461582889812915" localize="false">Exists</h2>
+ <paragraph role="paragraph" id="par_id841582889812916">Determine if a
key exists in the dictionary.</paragraph>
+ <h3 id="hd_id601582889812916" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functsyntax"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id311582889812917">myDict.Exists(Key As String) As Boolean</paragraph>
+ </bascode>
+ <h3 id="hd_id661582889812917" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functparameters"/></h3>
+ <paragraph role="paragraph"
id="par_id971582889812917"><emph>Key</emph> : The key to check.</paragraph>
+ <h3 id="hd_id231582889812918" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functexample"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id741582889812919">If Not myDict.Exists("newkey") Then</paragraph>
+ <paragraph role="bascode" id="bas_id471582889812919"> ' You may
add it safely to the dictionary</paragraph>
+ <paragraph role="bascode"
id="bas_id811606485130666">EndIf</paragraph>
+ </bascode>
+ </section>
+
+ <section id="ImportFromJson">
+ <comment> ImportFromJson
---------------------------------------------------------------------------------------------------------------------
</comment>
+ <bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id661601391980619">
+ <bookmark_value>Dictionary service;ImportFromJson</bookmark_value>
+ </bookmark>
+ <h2 id="hd_id81601391980848" localize="false">ImportFromJson</h2>
+ <paragraph role="paragraph" id="par_id791601391980978">Add the content
of a <link href="https://en.wikipedia.org/wiki/JSON"; name="JSON text">JSON
(JavaScript Object Notation)</link> text into the current dictionary. Returns
<literal>True</literal> if successful.</paragraph>
+ <h3 id="hd_id961601392113644" xml-lang="en-US">Limitations</h3>
+ <paragraph role="paragraph" id="par_id481601392181131"
xml-lang="en-US">The JSON string may contain numbers, text, booleans, null
values and arrays containing those types. It must not contain JSON objects
namely sub-dictionaries.</paragraph>
+ <paragraph role="paragraph" id="par_id511601392205908"
xml-lang="en-US">An attempt is made to convert text to date if the item fits
one of these patterns: YYYY-MM-DD, HH:MM:SS or YYYY-MM-DD HH:MM:SS.</paragraph>
+ <h3 id="hd_id301601391980982" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functsyntax"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id401601391980113">myDict.ImportFromJson(InputStr As String, [Overwrite
As Boolean]) As Boolean</paragraph>
+ </bascode>
+ <h3 id="hd_id871601391980130" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functparameters"/></h3>
+ <paragraph role="paragraph"
id="par_id69160139198061"><emph>InputStr</emph> : The string to
import.</paragraph>
+ <paragraph role="paragraph"
id="par_id201601391980268"><emph>Overwrite</emph> : when
<literal>True</literal>, entries with same name may exist in the dictionary and
their values are overwritten. When <literal>False</literal> (default), synonyms
raise an error. Note that dictionary keys are not case-sensitive while names
are case-sensitive in JSON strings.</paragraph>
+ <h3 id="hd_id141601391980338" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functexample"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id411601393205207">Dim s As String</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id891601393212562"> s = "{'firstName': 'John','lastName':
'Smith','isAlive': true,'age': 66, 'birth': '1954-09-28 20:15:00'"
_</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id221601393220997"> & ",'address': {'streetAddress': '21 2nd
Street','city': 'New York','state': 'NY','postalCode': '10021-3100'}"
_</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id931601393226582"> & ",'phoneNumbers': [{'type':
'home','number': '212 555-1234'},{'type': 'office','number': '646 555-4567'}]"
_</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id671601393233042"> & ",'children':
['Q','M','G','T'],'spouse': null}"</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id131601393240390"> s = Replace(s, "'", """")</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id351601393248554"> myDict.ImportFromJson(s, OverWrite :=
True)</paragraph>
+ <paragraph role="bascode" id="bas_id521601393254694"> '
The (sub)-dictionaries "address" and "phoneNumbers(0) and (1) are reduced to
Empty.</paragraph>
+ </bascode>
+ </section>
+
+ <section id="ImportFromPropertyValues">
+ <comment> ImportFromPropertyValues
---------------------------------------------------------------------------------------------------------------------
</comment>
+ <bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id791588941968651">
+ <bookmark_value>Dictionary
service;ImportFromPropertyValues</bookmark_value>
+ </bookmark>
+ <h2 id="hd_id71588941968955"
localize="false">ImportFromPropertyValues</h2>
+ <paragraph role="paragraph" id="par_id651588941968228">Insert the
content of an array of <literal>PropertyValues</literal> into the current
dictionary. Names contain the new keys, values contain the new items. Returns
<literal>True</literal> if successful.</paragraph>
+ <h3 id="hd_id82158894196854" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functsyntax"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id961588941968180">myDict.ImportFromPropertyValues(PropertyValues As
Variant [, Overwrite As Boolean]) As Boolean</paragraph>
+ </bascode>
+ <h3 id="hd_id271588941968528" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functparameters"/></h3>
+ <paragraph role="paragraph"
id="par_id751588941968522"><emph>PropertyValues</emph> : a zero-based 1
dimension array. Each entry is a UNO object of type
<literal>com.sun.star.beans.PropertyValue</literal>. The argument may also be a
single item.</paragraph>
+ <paragraph role="paragraph"
id="par_id21588941968131"><emph>Overwrite</emph> : when
<literal>True</literal>, entries with same name may exist in the dictionary and
their values are overwritten. When <literal>False</literal> (default), synonyms
raise an error. Note that dictionary keys are not case-sensitive while names
are case-sensitive in sets of property values.</paragraph>
+ <h3 id="hd_id501588941968965" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functexample"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id951588941968987">Dim vProp As New
com.sun.star.beans.PropertyValue</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id831588943409828"> vProp.Name = "prop" : vProp.Value =
CDateToUnoDateTime(Now)</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id771588941968883"> myDict.ImportFromPropertyValues(vProp, Overwrite
:= True)</paragraph>
+ </bascode>
+ </section>
+
+ <section id="Remove">
+ <comment> Remove
--------------------------------------------------------------------------------------------------------------------------
</comment>
+ <bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id741582890366762">
+ <bookmark_value>Dictionary service;Remove</bookmark_value>
+ </bookmark>
+ <h2 id="hd_id301582890366573" localize="false">Remove</h2>
+ <paragraph role="paragraph" id="par_id891582890366737">Remove an
existing dictionary entry based on its key. Returns <literal>True</literal> if
successful.</paragraph>
+ <h3 id="hd_id731582890366531" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functsyntax"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id71582890366664">myDict.Remove(Key As String) As Boolean</paragraph>
+ </bascode>
+ <h3 id="hd_id771582890366698" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functparameters"/></h3>
+ <paragraph role="paragraph"
id="par_id551582890366999"><emph>Key</emph> : Not case-sensitive. Must exist in
the dictionary, otherwise a <literal>UNKNOWNKEYERROR</literal> error is
generated.</paragraph>
+ <h3 id="hd_id81582890366375" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functexample"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id371582890366702">myDict.Remove("OldKey")</paragraph>
+ </bascode>
+ </section>
+
+ <section id="RemoveAll">
+ <comment> RemoveAll
--------------------------------------------------------------------------------------------------------------------------
</comment>
+ <bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id471582896275914">
+ <bookmark_value>Dictionary service;RemoveAll</bookmark_value>
+ </bookmark>
+ <h2 id="hd_id911582896275637" localize="false">RemoveAll</h2>
+ <paragraph role="paragraph" id="par_id921582896275624">Remove all the
entries from the dictionary. Returns <literal>True</literal> if
successful.</paragraph>
+ <h3 id="hd_id161582896275448" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functsyntax"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id56158289627581">myDict.RemoveAll() As Boolean</paragraph>
+ </bascode>
+ </section>
+
+ <section id="ReplaceItem">
+ <comment> ReplaceItem
--------------------------------------------------------------------------------------------------------------------------
</comment>
+ <bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id891582895615851">
+ <bookmark_value>Dictionary service;ReplaceItem</bookmark_value>
+ </bookmark>
+ <h2 id="hd_id801582895615477" localize="false">ReplaceItem</h2>
+ <paragraph role="paragraph" id="par_id281582895615444">Replace an
existing item value based on its key. Returns <literal>True</literal> if
successful.</paragraph>
+ <h3 id="hd_id66158289561569" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functsyntax"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id51582895615226">myDict.ReplaceItem(Key As String, Value As Variant)
As Boolean</paragraph>
+ </bascode>
+ <h3 id="hd_id521582895615249" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functparameters"/></h3>
+ <paragraph role="paragraph"
id="par_id991582895615535"><emph>Key</emph> : Not case-sensitive. Must exist in
the dictionary, otherwise a <literal>UNKNOWNKEYERROR</literal> error is
generated.</paragraph>
+ <paragraph role="paragraph"
id="par_id721582895615186"><emph>Value</emph> : The new value of the item part
of the dictionary entry.</paragraph>
+ <h3 id="hd_id781582895615372" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functexample"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id581582895615680">Dim NewValue As Variant</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id351582895615555"> myDict.ReplaceItem("ExistingKey",
NewValue)</paragraph>
+ </bascode>
+ </section>
+
+ <section id="ReplaceKey">
+ <comment> ReplaceKey
--------------------------------------------------------------------------------------------------------------------------
</comment>
+ <bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id411582896597981">
+ <bookmark_value>Dictionary service;ReplaceKey</bookmark_value>
+ </bookmark>
+ <h2 id="hd_id231582896597839" localize="false">ReplaceKey</h2>
+ <paragraph role="paragraph" id="par_id571582896597766">Replace an
existing key with a new value. The item part is left unchanged. Returns
<literal>True</literal> if successful.</paragraph>
+ <h3 id="hd_id441582896597550" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functsyntax"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id351582896597447">myDict.ReplaceKey(Key As String, Value As String) As
Boolean</paragraph>
+ </bascode>
+ <h3 id="hd_id791582896597306" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functparameters"/></h3>
+ <paragraph role="paragraph"
id="par_id911582896597619"><emph>Key</emph> : Not case-sensitive. Must exist in
the dictionary, otherwise a <literal>UNKNOWNKEYERROR</literal> error is
generated.</paragraph>
+ <paragraph role="paragraph"
id="par_id531582896597989"><emph>Value</emph> : Not case-sensitive. Must exist
in the dictionary, otherwise a <literal>DUPLICATEKEYERROR</literal> error is
generated.</paragraph>
+ <h3 id="hd_id931582896597782" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functexample"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id521582896597313"> myDict.ReplaceKey("OldKey", "NewKey")</paragraph>
+ </bascode>
+ </section>
+
+</body>
+</helpdocument>
diff --git a/source/text/sbasic/shared/03/sf_dictionary.xhp
b/source/text/sbasic/shared/03/sf_dictionary.xhp
new file mode 100644
index 000000000..d37af6f49
--- /dev/null
+++ b/source/text/sbasic/shared/03/sf_dictionary.xhp
@@ -0,0 +1,410 @@
+<?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_Dictionary" indexer="include" status="PUBLISH">
+ <title id="tit" xml-lang="en-US">ScriptForge.Dictionary service</title>
+ <filename>/text/sbasic/shared/03/sf_dictionary.xhp</filename>
+ </topic>
+</meta>
+<body>
+<section id="abstract">
+ <bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id261582733781987">
+ <bookmark_value>Dictionary service</bookmark_value>
+ <bookmark_value>API;DateTime</bookmark_value>
+ <bookmark_value>API;PropertyValue</bookmark_value>
+ </bookmark>
+
+ <h1 id="hd_id731582733781114"
xml-lang="en-US"><literal>ScriptForge</literal>.<literal>Dictionary</literal>
service</h1>
+
+ <paragraph role="paragraph" id="par_id891582884466217" xml-lang="en-US">A
dictionary is a collection of key-item pairs</paragraph>
+ <list type="unordered">
+ <listitem><paragraph id="par_id861582884516571" role="listitem"
xml-lang="en-US">The key is a case-insensitive string</paragraph></listitem>
+ <listitem><paragraph id="par_id531582884549542" role="listitem"
xml-lang="en-US">Items may be of any type</paragraph></listitem>
+ </list>
+</section>
+
+ <paragraph role="paragraph" id="par_id891582884593057" xml-lang="en-US">Keys
and items can be retrieved, counted, updated, and much more.</paragraph>
+ <paragraph role="tip" id="par_id971582884636922"
xml-lang="en-US">%PRODUCTNAME Basic <literal>Collection</literal> object does
not support the retrieval of the keys.
+ <br/>Additionally its items contain only primitive Basic data types such as
dates, text, numbers, and the like.</paragraph>
+
+ <h2 id="hd_id581582885621841" xml-lang="en-US">Service invocation</h2>
+
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id851582897798335">GlobalScope.BasicLibraries.loadLibrary("ScriptForge")</paragraph>
+ <paragraph role="bascode" localize="false" id="bas_id371582885621964">Dim
myDict As Variant</paragraph>
+ <paragraph role="bascode" localize="false" id="bas_id201582885621287">
myDict = CreateScriptService("Dictionary")</paragraph>
+ </bascode>
+
+ <paragraph role="paragraph" id="par_id71158288562139" xml-lang="en-US">It is
recommended to free resources after use:</paragraph>
+ <bascode>
+ <paragraph role="bascode" localize="false" id="bas_id721582885621540">Set
myDict = myDict.Dispose()</paragraph>
+ </bascode>
+
+ <embed href="text/sbasic/shared/03/lib_ScriptForge.xhp#SF_InternalUse"/>
+
+ <h2 id="hd_id351582885195476" xml-lang="en-US">Properties</h2>
+ <section id="Item">
+ <table id="tab_id971582885195582">
+ <tablerow>
+ <tablecell>
+ <paragraph id="par_id41582885195836" role="tablehead"
xml-lang="en-US">Name</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id31582885195372" role="tablehead"
xml-lang="en-US">Readonly</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id501582885895609" role="tablehead"
xml-lang="en-US">Argument</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id31582885195238" role="tablehead"
xml-lang="en-US">Type</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id931582885195131" role="tablehead"
xml-lang="en-US" >Description</paragraph>
+ </tablecell>
+ </tablerow>
+ <tablerow>
+ <tablecell>
+ <paragraph id="par_id97158288519551" role="tablecontent"
localize="false">Count</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id221582885195686" role="tablecontent"
xml-lang="en-US">Yes</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id851582885948589" role="tablecontent"
localize="false"></paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id371582885195525" role="tablecontent"
localize="false">Long</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id881582885195976" role="tablecontent"
xml-lang="en-US">The actual number of entries in the dictionary</paragraph>
+ </tablecell>
+ </tablerow>
+ <tablerow>
+ <tablecell>
+ <paragraph id="par_id7715828856553" role="tablecontent"
localize="false">Item</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id861582885655779" role="tablecontent"
xml-lang="en-US">Yes</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id621582885990445" role="tablecontent"
localize="false">Key As String</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id271582885655525" role="tablecontent"
localize="false">Variant</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id581582885655885" role="tablecontent"
xml-lang="en-US">The value of the item related to <literal>Key</literal><br
/><literal>Empty</literal> if not found</paragraph>
+ </tablecell>
+ </tablerow>
+ <tablerow>
+ <tablecell>
+ <paragraph id="par_id841582886030384" role="tablecontent"
localize="false">Items</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id441582886030118" role="tablecontent"
xml-lang="en-US">Yes</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id411582886030478" role="tablecontent"
localize="false"></paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id131582886030297" role="tablecontent"
xml-lang="en-US">Array of Variants</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id471582886030489" role="tablecontent"
xml-lang="en-US">The list of items as a one dimension array</paragraph>
+ </tablecell>
+ </tablerow>
+ <tablerow>
+ <tablecell>
+ <paragraph id="par_id231582886791351" role="tablecontent"
localize="false">Keys</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id971582886791838" role="tablecontent"
xml-lang="en-US">Yes</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id721582886791467" role="tablecontent"
localize="false"></paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id271582886791111" role="tablecontent"
xml-lang="en-US">Array of Strings</paragraph>
+ </tablecell>
+ <tablecell>
+ <paragraph id="par_id16158288679167" role="tablecontent"
xml-lang="en-US">The list of keys as a one dimension array</paragraph>
+ </tablecell>
+ </tablerow>
+ </table>
+ </section>
+
+ <paragraph role="tip" id="par_id461582886731495" xml-lang="en-US">The Keys
and Items properties return their respective contents, using an identical
ordering.
+ <br/>The order is unrelated to the creation sequence.</paragraph>
+
+ <h3 id="hd_id691582887572811" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functexample"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false" id="bas_id211582887012398">Dim
a As Variant, b As String</paragraph>
+ <paragraph role="bascode" localize="false" id="bas_id351582887179042">
a = myDict.Keys</paragraph>
+ <paragraph role="bascode" localize="false" id="bas_id251582887187534">
For Each b In a</paragraph>
+ <paragraph role="bascode" localize="false" id="bas_id121582887198799">
' ...</paragraph>
+ <paragraph role="bascode" localize="false" id="bas_id571606473148931">
Next b</paragraph>
+ </bascode>
+
+ <table id="tab_id891606472825856">
+ <tablerow>
+ <tablecell><paragraph id="par_id581606472825856" role="tablehead"
localize="false"></paragraph></tablecell>
+ <tablecell><paragraph id="par_id921606472825856"
role="tablehead">Methods</paragraph></tablecell>
+ <tablecell><paragraph id="par_id781606472825856" role="tablehead"
localize="false"></paragraph></tablecell>
+ </tablerow>
+ <tablerow>
+ <tablecell><paragraph id="par_id381606472825856" role="tablecontent">
+ <link href="text/sbasic/shared/03/sf_dictionary.xhp#Add" name="Add
method">Add</link><br/><br/>
+ <link href="text/sbasic/shared/03/sf_dictionary.xhp#ConvertToArray"
name="ConvertToArray method">ConvertToArray</link><br/>
+ <link href="text/sbasic/shared/03/sf_dictionary.xhp#ConvertToJson"
name="ConvertToJson method">ConvertToJson</link><br/>
+ <link
href="text/sbasic/shared/03/sf_dictionary.xhp#ConvertToPropertyValues"
name="ConvertToPropertyValues method">ConvertToPropertyValues</link>
+ </paragraph></tablecell>
+ <tablecell><paragraph id="par_id451606472825856" role="tablecontent">
+ <link href="text/sbasic/shared/03/sf_dictionary.xhp#Exists"
name="Exists method">Exists</link><br/><br/>
+ <link href="text/sbasic/shared/03/sf_dictionary.xhp#ImportFromJson"
name="ImportFromJson method">ImportFromJson</link><br/>
+ <link
href="text/sbasic/shared/03/sf_dictionary.xhp#ImportFromPropertyValues"
name="ImportFromPropertyValues method">ImportFromPropertyValues</link><br/>
+ <link href="text/sbasic/shared/03/sf_dictionary.xhp#Item"
name="Item method">Item</link>
+ </paragraph></tablecell>
+ <tablecell><paragraph id="par_id161606472825856" role="tablecontent">
+ <link href="text/sbasic/shared/03/sf_dictionary.xhp#Remove"
name="Remove method">Remove</link><br/>
+ <link href="text/sbasic/shared/03/sf_dictionary.xhp#RemoveAll"
name="RemoveAll method">RemoveAll</link><br/>
+ <link href="text/sbasic/shared/03/sf_dictionary.xhp#ReplaceItem"
name="ReplaceItem method">ReplaceItem</link><br/>
+ <link href="text/sbasic/shared/03/sf_dictionary.xhp#ReplaceKey"
name="ReplaceKey method">ReplaceKey</link>
+ </paragraph></tablecell>
+ </tablerow>
+ </table>
+
+ <section id="Add">
+ <comment> Add
--------------------------------------------------------------------------------------------------------------------------
</comment>
+ <bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id781582887670029">
+ <bookmark_value>Dictionary service;Add</bookmark_value>
+ </bookmark>
+ <h2 id="hd_id831582887670029" localize="false">Add</h2>
+ <paragraph role="paragraph" id="par_id831582887670029">Add a new
key-item pair into the dictionary. Returns <literal>True</literal> if
successful.</paragraph>
+ <h3 id="hd_id451582887670029" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functsyntax"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id731582887670029">myDict.Add(Key As String, Item As Variant) As
Boolean</paragraph>
+ </bascode>
+ <h3 id="hd_id821582887670030" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functparameters"/></h3>
+ <paragraph role="paragraph"
id="par_id341582887670030"><emph>Key</emph> : Not case-sensitive. Must not yet
exist in the dictionary, otherwise a <literal>DUPLICATEKEYERROR</literal> error
is generated. Spaces only generate a <literal>INVALIDKEYERROR</literal>
error.</paragraph>
+ <paragraph role="paragraph"
id="par_id401582887670030"><emph>Item</emph> : Any value, including an array, a
Basic object, a UNO object, a dictionary, ...</paragraph>
+ <h3 id="hd_id461582887670030" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functexample"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id191582887670030">Dim NewValue As Variant</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id391582887670030"> myDict.Add("NewKey", NewValue)</paragraph>
+ </bascode>
+ </section>
+
+ <section id="ConvertToArray">
+ <comment> ConvertToArray
--------------------------------------------------------------------------------------------------------------------------
</comment>
+ <bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id621582888424103">
+ <bookmark_value>Dictionary service;ConvertToArray</bookmark_value>
+ </bookmark>
+ <h2 id="hd_id211582888424104" localize="false">ConvertToArray</h2>
+ <paragraph role="paragraph" id="par_id81582888424104">Store the
content of the dictionary in a two-columns zero-based array. The key is stored
in the first column, the item is stored in the second column.
+ <br />The resulting array is empty when the dictionary is
empty.</paragraph>
+ <h3 id="hd_id201582888424104" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functsyntax"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id251582888424105">myDict.ConvertToArray() As Variant</paragraph>
+ </bascode>
+ </section>
+
+ <section id="ConvertToJson">
+ <comment> ConvertToJson
---------------------------------------------------------------------------------------------------------------------
</comment>
+ <bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id631601296836318">
+ <bookmark_value>Dictionary service;ConvertToJson</bookmark_value>
+ </bookmark>
+ <h2 id="hd_id851601296836224" localize="false">ConvertToJson</h2>
+ <paragraph role="paragraph" id="par_id831601296836981">Convert the
content of the dictionary to <link href="https://en.wikipedia.org/wiki/JSON";
name="JSON text">JSON (JavaScript Object Notation)</link> text.</paragraph>
+ <h3 id="hd_id261601297024828" xml-lang="en-US">Limitations</h3>
+ <paragraph role="paragraph" id="par_id401601297178073"
xml-lang="en-US">Allowed data types are: <literal>String</literal>,
<literal>Boolean</literal>, numbers, <literal>Null</literal> and
<literal>Empty</literal>. Arrays containing items of those types are allowed,
whatever their dimensions. Dates are converted into strings but not within
arrays where they are forbidden. Other data types are converted to their string
representation (cfr. SF_String.Represent).</paragraph>
+ <h3 id="hd_id551601296836572" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functsyntax"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id491601296836271">myDict.ConvertToJson([Indent As Variant]) As
String</paragraph>
+ </bascode>
+ <h3 id="hd_id1001601296836123" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functparameters"/></h3>
+ <paragraph role="paragraph" id="par_id8816012968362"><emph>Indent</emph>
: When <literal>Indent</literal> is a positive number or a text, JSON array
elements and object members are pretty-printed with that indent level. A
negative <literal>Indent</literal> value solely insert new lines.
<literal>Indent</literal> default value "" selects the most compact
representation. Using a positive integer for <literal>Indent</literal> indents
that many spaces per level. When <literal>Indent</literal> is a string, such as
<literal>Chr(9)</literal> or <literal>Tab(1)</literal>, the tab sign is used to
indent each level.</paragraph>
+ <h3 id="hd_id19160129683665" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functexample"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id671601298281962">myDict.Add("p0", 12.5)</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id851601298288784">myDict.Add("p1", "a string àé""ê")</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id201601298295976">myDict.Add("p2", DateSerial(2020,9,28))</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id951601298323286">myDict.Add("p3", True)</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id731601298329491">myDict.Add("p4", Array(1,2,3))</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id451601298336500">MsgBox a.ConvertToJson() ' {"p0": 12.5, "p1":
"a string \u00e0\u00e9\"\u00ea", "p2": "2020-09-28", "p3": true, "p4": [1, 2,
3]}</paragraph>
+ </bascode>
+ </section>
+
+ <section id="ConvertToPropertyValues">
+ <comment> ConvertToPropertyValues
-----------------------------------------------------------------------------------------------------------------------
</comment>
+ <bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id991582889470402">
+ <bookmark_value>Dictionary
service;ConvertToPropertyValues</bookmark_value>
+ </bookmark>
+ <h2 id="hd_id421582889470909"
localize="false">ConvertToPropertyValues</h2>
+ <paragraph role="paragraph" id="par_id151582889470596">Store the
content of the dictionary in an array of <literal>PropertyValues</literal>.
+ <br />Each entry in the array is a
<literal>com.sun.star.beans.PropertyValue</literal>. The key is stored in
<literal>Name</literal>, the item is stored in <literal>Value</literal>.
+ <br />If one of the items has a type <literal>Date</literal>, it is
converted to a <literal>com.sun.star.util.DateTime</literal> structure.
+ <br />If one of the items is an empty array, it is converted to
<literal>Null</literal>.
+ <br />The resulting array is empty when the dictionary is
empty.</paragraph>
+ <h3 id="hd_id841582889470464" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functsyntax"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id191582889470444">myDict.ConvertToPropertyValues() As
Variant</paragraph>
+ </bascode>
+ </section>
+
+ <section id="Exists">
+ <comment> Exists
--------------------------------------------------------------------------------------------------------------------------
</comment>
+ <bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id81582889812915">
+ <bookmark_value>Dictionary service;Exists</bookmark_value>
+ </bookmark>
+ <h2 id="hd_id461582889812915" localize="false">Exists</h2>
+ <paragraph role="paragraph" id="par_id841582889812916">Determine if a
key exists in the dictionary.</paragraph>
+ <h3 id="hd_id601582889812916" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functsyntax"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id311582889812917">myDict.Exists(Key As String) As Boolean</paragraph>
+ </bascode>
+ <h3 id="hd_id661582889812917" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functparameters"/></h3>
+ <paragraph role="paragraph"
id="par_id971582889812917"><emph>Key</emph> : The key to check.</paragraph>
+ <h3 id="hd_id231582889812918" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functexample"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id741582889812919">If Not myDict.Exists("newkey") Then</paragraph>
+ <paragraph role="bascode" id="bas_id471582889812919"> ' You may
add it safely to the dictionary</paragraph>
+ <paragraph role="bascode"
id="bas_id811606485130666">EndIf</paragraph>
+ </bascode>
+ </section>
+
+ <section id="ImportFromJson">
+ <comment> ImportFromJson
---------------------------------------------------------------------------------------------------------------------
</comment>
+ <bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id661601391980619">
+ <bookmark_value>Dictionary service;ImportFromJson</bookmark_value>
+ </bookmark>
+ <h2 id="hd_id81601391980848" localize="false">ImportFromJson</h2>
+ <paragraph role="paragraph" id="par_id791601391980978">Add the content
of a <link href="https://en.wikipedia.org/wiki/JSON"; name="JSON text">JSON
(JavaScript Object Notation)</link> text into the current dictionary. Returns
<literal>True</literal> if successful.</paragraph>
+ <h3 id="hd_id961601392113644" xml-lang="en-US">Limitations</h3>
+ <paragraph role="paragraph" id="par_id481601392181131"
xml-lang="en-US">The JSON string may contain numbers, text, booleans, null
values and arrays containing those types. It must not contain JSON objects
namely sub-dictionaries.</paragraph>
+ <paragraph role="paragraph" id="par_id511601392205908"
xml-lang="en-US">An attempt is made to convert text to date if the item fits
one of these patterns: YYYY-MM-DD, HH:MM:SS or YYYY-MM-DD HH:MM:SS.</paragraph>
+ <h3 id="hd_id301601391980982" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functsyntax"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id401601391980113">myDict.ImportFromJson(InputStr As String, [Overwrite
As Boolean]) As Boolean</paragraph>
+ </bascode>
+ <h3 id="hd_id871601391980130" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functparameters"/></h3>
+ <paragraph role="paragraph"
id="par_id69160139198061"><emph>InputStr</emph> : The string to
import.</paragraph>
+ <paragraph role="paragraph"
id="par_id201601391980268"><emph>Overwrite</emph> : when
<literal>True</literal>, entries with same name may exist in the dictionary and
their values are overwritten. When <literal>False</literal> (default), synonyms
raise an error. Note that dictionary keys are not case-sensitive while names
are case-sensitive in JSON strings.</paragraph>
+ <h3 id="hd_id141601391980338" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functexample"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id411601393205207">Dim s As String</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id891601393212562"> s = "{'firstName': 'John','lastName':
'Smith','isAlive': true,'age': 66, 'birth': '1954-09-28 20:15:00'"
_</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id221601393220997"> & ",'address': {'streetAddress': '21 2nd
Street','city': 'New York','state': 'NY','postalCode': '10021-3100'}"
_</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id931601393226582"> & ",'phoneNumbers': [{'type':
'home','number': '212 555-1234'},{'type': 'office','number': '646 555-4567'}]"
_</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id671601393233042"> & ",'children':
['Q','M','G','T'],'spouse': null}"</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id131601393240390"> s = Replace(s, "'", """")</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id351601393248554"> myDict.ImportFromJson(s, OverWrite :=
True)</paragraph>
+ <paragraph role="bascode" id="bas_id521601393254694"> '
The (sub)-dictionaries "address" and "phoneNumbers(0) and (1) are reduced to
Empty.</paragraph>
+ </bascode>
+ </section>
+
+ <section id="ImportFromPropertyValues">
+ <comment> ImportFromPropertyValues
---------------------------------------------------------------------------------------------------------------------
</comment>
+ <bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id791588941968651">
+ <bookmark_value>Dictionary
service;ImportFromPropertyValues</bookmark_value>
+ </bookmark>
+ <h2 id="hd_id71588941968955"
localize="false">ImportFromPropertyValues</h2>
+ <paragraph role="paragraph" id="par_id651588941968228">Insert the
content of an array of <literal>PropertyValues</literal> into the current
dictionary. Names contain the new keys, values contain the new items. Returns
<literal>True</literal> if successful.</paragraph>
+ <h3 id="hd_id82158894196854" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functsyntax"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id961588941968180">myDict.ImportFromPropertyValues(PropertyValues As
Variant [, Overwrite As Boolean]) As Boolean</paragraph>
+ </bascode>
+ <h3 id="hd_id271588941968528" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functparameters"/></h3>
+ <paragraph role="paragraph"
id="par_id751588941968522"><emph>PropertyValues</emph> : a zero-based 1
dimension array. Each entry is a UNO object of type
<literal>com.sun.star.beans.PropertyValue</literal>. The argument may also be a
single item.</paragraph>
+ <paragraph role="paragraph"
id="par_id21588941968131"><emph>Overwrite</emph> : when
<literal>True</literal>, entries with same name may exist in the dictionary and
their values are overwritten. When <literal>False</literal> (default), synonyms
raise an error. Note that dictionary keys are not case-sensitive while names
are case-sensitive in sets of property values.</paragraph>
+ <h3 id="hd_id501588941968965" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functexample"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id951588941968987">Dim vProp As New
com.sun.star.beans.PropertyValue</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id831588943409828"> vProp.Name = "prop" : vProp.Value =
CDateToUnoDateTime(Now)</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id771588941968883"> myDict.ImportFromPropertyValues(vProp, Overwrite
:= True)</paragraph>
+ </bascode>
+ </section>
+
+ <section id="Remove">
+ <comment> Remove
--------------------------------------------------------------------------------------------------------------------------
</comment>
+ <bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id741582890366762">
+ <bookmark_value>Dictionary service;Remove</bookmark_value>
+ </bookmark>
+ <h2 id="hd_id301582890366573" localize="false">Remove</h2>
+ <paragraph role="paragraph" id="par_id891582890366737">Remove an
existing dictionary entry based on its key. Returns <literal>True</literal> if
successful.</paragraph>
+ <h3 id="hd_id731582890366531" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functsyntax"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id71582890366664">myDict.Remove(Key As String) As Boolean</paragraph>
+ </bascode>
+ <h3 id="hd_id771582890366698" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functparameters"/></h3>
+ <paragraph role="paragraph"
id="par_id551582890366999"><emph>Key</emph> : Not case-sensitive. Must exist in
the dictionary, otherwise a <literal>UNKNOWNKEYERROR</literal> error is
generated.</paragraph>
+ <h3 id="hd_id81582890366375" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functexample"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id371582890366702">myDict.Remove("OldKey")</paragraph>
+ </bascode>
+ </section>
+
+ <section id="RemoveAll">
+ <comment> RemoveAll
--------------------------------------------------------------------------------------------------------------------------
</comment>
+ <bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id471582896275914">
+ <bookmark_value>Dictionary service;RemoveAll</bookmark_value>
+ </bookmark>
+ <h2 id="hd_id911582896275637" localize="false">RemoveAll</h2>
+ <paragraph role="paragraph" id="par_id921582896275624">Remove all the
entries from the dictionary. Returns <literal>True</literal> if
successful.</paragraph>
+ <h3 id="hd_id161582896275448" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functsyntax"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id56158289627581">myDict.RemoveAll() As Boolean</paragraph>
+ </bascode>
+ </section>
+
+ <section id="ReplaceItem">
+ <comment> ReplaceItem
--------------------------------------------------------------------------------------------------------------------------
</comment>
+ <bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id891582895615851">
+ <bookmark_value>Dictionary service;ReplaceItem</bookmark_value>
+ </bookmark>
+ <h2 id="hd_id801582895615477" localize="false">ReplaceItem</h2>
+ <paragraph role="paragraph" id="par_id281582895615444">Replace an
existing item value based on its key. Returns <literal>True</literal> if
successful.</paragraph>
+ <h3 id="hd_id66158289561569" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functsyntax"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id51582895615226">myDict.ReplaceItem(Key As String, Value As Variant)
As Boolean</paragraph>
+ </bascode>
+ <h3 id="hd_id521582895615249" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functparameters"/></h3>
+ <paragraph role="paragraph"
id="par_id991582895615535"><emph>Key</emph> : Not case-sensitive. Must exist in
the dictionary, otherwise a <literal>UNKNOWNKEYERROR</literal> error is
generated.</paragraph>
+ <paragraph role="paragraph"
id="par_id721582895615186"><emph>Value</emph> : The new value of the item part
of the dictionary entry.</paragraph>
+ <h3 id="hd_id781582895615372" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functexample"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id581582895615680">Dim NewValue As Variant</paragraph>
+ <paragraph role="bascode" localize="false"
id="bas_id351582895615555"> myDict.ReplaceItem("ExistingKey",
NewValue)</paragraph>
+ </bascode>
+ </section>
+
+ <section id="ReplaceKey">
+ <comment> ReplaceKey
--------------------------------------------------------------------------------------------------------------------------
</comment>
+ <bookmark xml-lang="en-US" localize="false" branch="index"
id="bm_id411582896597981">
+ <bookmark_value>Dictionary service;ReplaceKey</bookmark_value>
+ </bookmark>
+ <h2 id="hd_id231582896597839" localize="false">ReplaceKey</h2>
+ <paragraph role="paragraph" id="par_id571582896597766">Replace an
existing key with a new value. The item part is left unchanged. Returns
<literal>True</literal> if successful.</paragraph>
+ <h3 id="hd_id441582896597550" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functsyntax"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id351582896597447">myDict.ReplaceKey(Key As String, Value As String) As
Boolean</paragraph>
+ </bascode>
+ <h3 id="hd_id791582896597306" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functparameters"/></h3>
+ <paragraph role="paragraph"
id="par_id911582896597619"><emph>Key</emph> : Not case-sensitive. Must exist in
the dictionary, otherwise a <literal>UNKNOWNKEYERROR</literal> error is
generated.</paragraph>
+ <paragraph role="paragraph"
id="par_id531582896597989"><emph>Value</emph> : Not case-sensitive. Must exist
in the dictionary, otherwise a <literal>DUPLICATEKEYERROR</literal> error is
generated.</paragraph>
+ <h3 id="hd_id931582896597782" localize="false"><embedvar
href="text/sbasic/shared/00000003.xhp#functexample"/></h3>
+ <bascode>
+ <paragraph role="bascode" localize="false"
id="bas_id521582896597313"> myDict.ReplaceKey("OldKey", "NewKey")</paragraph>
+ </bascode>
+ </section>
+
+</body>
+</helpdocument>
_______________________________________________
Libreoffice-commits mailing list
libreoffice-comm...@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/libreoffice-commits
