diff options
| -rw-r--r-- | AllLangHelp_sbasic.mk | 2 | ||||
| -rw-r--r-- | source/text/sbasic/shared/03/lib_ScriptForge.xhp | 21 | ||||
| -rw-r--r-- | source/text/sbasic/shared/03/sf_array.xhp | 410 | ||||
| -rw-r--r-- | source/text/sbasic/shared/03/sf_dictionary.xhp | 410 |
4 files changed, 835 insertions, 8 deletions
diff --git a/AllLangHelp_sbasic.mk b/AllLangHelp_sbasic.mk index 7423e9ebad..71d311cdf4 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 c0f33a9c9a..ef5f49d247 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 0000000000..d37af6f49d --- /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 0000000000..d37af6f49d --- /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> |