tdf#146117 Explain that Var/Str are locale-independent

Change-Id: I0a90befe2c63e8f9719ec7179666c9342602d0e2
Reviewed-on: https://gerrit.libreoffice.org/c/help/+/127782
Tested-by: Jenkins
Reviewed-by: Olivier Hallot <olivier.hallot@libreoffice.org>
Reviewed-by: Mike Kaganski <mike.kaganski@collabora.com>

2 files changed, 54 insertions, 18 deletions

diff --git a/source/text/sbasic/shared/03120103.xhp b/source/text/sbasic/shared/03120103.xhp
index be43bfa28b..976c53e7e3 100644
--- a/source/text/sbasic/shared/03120103.xhp
+++ b/source/text/sbasic/shared/03120103.xhp
@@ -30,30 +30,56 @@
     <bookmark xml-lang="en-US" branch="index" id="bm_id3143272">
       <bookmark_value>Str function</bookmark_value>
     </bookmark>
-    <h1 id="hd_id3143272"><link href="text/sbasic/shared/03120103.xhp" name="Str Function">Str Function</link></h1>
-    <paragraph id="par_id3155100" role="paragraph">Converts a numeric expression into a string.</paragraph>
+    <h1 id="hd_id3143272"><variable id="Str_h1"><link href="text/sbasic/shared/03120103.xhp" name="Str Function">Str Function</link></variable></h1>
+    <paragraph id="par_id3155100" role="paragraph">The <literal>Str</literal> function converts the contents of variables into a string. It handles numeric values, dates, strings and currency values.</paragraph>
+    <paragraph id="par_id3146958" role="paragraph">Positive numbers are preceded by a blank space. Negative numbers are preceded by a minus sign.</paragraph>
+    <note id="par_id331641237252390">For numeric values the string returned by the <literal>Str</literal> function is locale-independent. Hence the dot is used as the decimal separator when needed.</note>
+    <paragraph role="paragraph" id="par_id601641237849695">If a string is passed as argument, it is returned without any changes.</paragraph>
+    <paragraph role="paragraph" id="par_id231641251937406">Dates are converted into locale-dependent strings.</paragraph>
   </section>
   <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
   <bascode>
-    <paragraph id="par_id3149497" role="bascode">Str (Expression)</paragraph>
+    <paragraph id="par_id3149497" role="bascode">Str (Value As Variant)</paragraph>
   </bascode>
   <embed href="text/sbasic/shared/00000003.xhp#functvalue"/>
   <paragraph id="par_id3146117" localize="false" role="paragraph">String</paragraph>
   <embed href="text/sbasic/shared/00000003.xhp#functparameters"/>
-  <paragraph id="par_id3149178" role="paragraph"> <emph>Expression: </emph>Any numeric expression.</paragraph>
-  <paragraph id="par_id3146958" role="paragraph">The <emph>Str</emph> function converts a numeric variable, or the result of a calculation into a string. Negative numbers are preceded by a minus sign. Positive numbers are preceded by a space (instead of the plus sign).</paragraph>
+  <paragraph id="par_id3149178" role="paragraph"> <emph>Value:</emph> Any value to be converted into a string.</paragraph>
   <embed href="text/sbasic/shared/00000003.xhp#errorcode"/>
   <embed href="text/sbasic/shared/00000003.xhp#err5"/>
   <embed href="text/sbasic/shared/00000003.xhp#functexample"/>
+  <paragraph role="paragraph" id="par_id401641251970766">Below are some numeric examples using the <literal>Str</literal> function.</paragraph>
   <bascode>
-    <paragraph id="par_idm1341439760" role="bascode" localize="false">Sub ExampleStr</paragraph>
-    <paragraph id="par_idm1341438528" role="bascode" localize="false">    Dim iVar As Single</paragraph>
-    <paragraph id="par_idm1341437296" role="bascode" localize="false">    Dim sVar As String</paragraph>
-    <paragraph id="par_idm1341436064" role="bascode" localize="false">    iVar = 123.123</paragraph>
-    <paragraph id="par_idm1341434832" role="bascode" localize="false">    sVar = LTrim(Str(iVar))</paragraph>
-    <paragraph id="par_idm1341433584" role="bascode" localize="false">    MsgBox sVar &amp; chr(13) &amp; Str(iVar)</paragraph>
+    <paragraph id="par_idm1341439760" role="bascode" localize="false">Sub ExampleStr_1</paragraph>
+    <paragraph role="bascode" id="bas_id831641238784987">    ' Note the blank space at the beginning of the returned strings</paragraph>
+    <paragraph id="par_idm1341438528" role="bascode" localize="false">    MsgBox Str(10) ' " 10"</paragraph>
+    <paragraph id="par_idm1341437296" role="bascode" localize="false">    MsgBox Str(10.5) ' " 10.5"</paragraph>
+    <paragraph id="par_idm1341436064" role="bascode" localize="false">    MsgBox Str(-12345 + 1.3) ' " -12346.3"</paragraph>
+    <paragraph id="par_idm1341434832" role="bascode" localize="false">    MsgBox Str(10000 / 3) '  " 3333.33333333333"</paragraph>
+    <paragraph role="bascode" id="bas_id991641238830710">    ' Strings passed as arguments are left unchanged</paragraph>
+    <paragraph id="par_idm1341433584" role="bascode" localize="false">    MsgBox Str("A123") ' "A123"</paragraph>
     <paragraph id="par_idm1341432272" role="bascode" localize="false">End Sub</paragraph>
   </bascode>
-</body>
+  <paragraph role="paragraph" id="par_id601641238259787">Use the <literal>LTrim</literal> function to remove the blank space at the beginning of the returned string.</paragraph>
+  <bascode>
+    <paragraph role="bascode" localize="false" id="bas_id521641238327633">Sub ExampleStr_2</paragraph>
+    <paragraph role="bascode" localize="false" id="bas_id211641238327951">    MsgBox Str(10.5) ' " 10.5"</paragraph>
+    <paragraph role="bascode" localize="false" id="bas_id481641238328191">    MsgBox LTrim(Str(10.5)) ' "10.5"</paragraph>
+    <paragraph role="bascode" localize="false" id="bas_id51641238328726">End Sub</paragraph>
+  </bascode>
+  <paragraph role="paragraph" id="par_id881641252036753">The <literal>Str</literal> function can also handle <literal>Date</literal> variables.</paragraph>
+  <bascode>
+    <paragraph role="bascode" localize="false" id="bas_id781641252076979">Sub ExampleStr_3</paragraph>
+    <paragraph role="bascode" localize="false" id="bas_id271641252077387">    Dim aDate as Date, aTime as Date</paragraph>
+    <paragraph role="bascode" localize="false" id="bas_id816412520776129">    aDate = DateSerial(2021, 12, 20)</paragraph>
+    <paragraph role="bascode" localize="false" id="bas_id631641252077803">    aTime = TimeSerial(10, 20, 45)</paragraph>
+    <paragraph role="bascode" localize="false" id="bas_id311641252078019">    Print Str(aDate) ' "12/20/2021"</paragraph>
+    <paragraph role="bascode" localize="false" id="bas_id481641252230128">    Print Str(aTime) ' "10:20:45"</paragraph>
+    <paragraph role="bascode" localize="false" id="bas_id481641252078235">End sub</paragraph>
+  </bascode>
 
+  <section id="relatedtopics">
+    <embed href="text/sbasic/shared/03120104.xhp#Val_h1"/>
+  </section>
+</body>
 </helpdocument>
diff --git a/source/text/sbasic/shared/03120104.xhp b/source/text/sbasic/shared/03120104.xhp
index f2738a4f74..b83dc56258 100644
--- a/source/text/sbasic/shared/03120104.xhp
+++ b/source/text/sbasic/shared/03120104.xhp
@@ -30,8 +30,9 @@
     <bookmark xml-lang="en-US" branch="index" id="bm_id3149205">
       <bookmark_value>Val function</bookmark_value>
     </bookmark>
-    <h1 id="hd_id3149205"><link href="text/sbasic/shared/03120104.xhp" name="Val Function">Val Function</link></h1>
-    <paragraph id="par_id3153345" role="paragraph">Converts a string to a numeric expression.</paragraph>
+    <h1 id="hd_id3149205"><variable id="Val_h1"><link href="text/sbasic/shared/03120104.xhp" name="Val Function">Val Function</link></variable></h1>
+    <paragraph id="par_id3153345" role="paragraph">Use the <literal>Val</literal> function to convert a string that represents a number into numeric data type.</paragraph>
+    <note id="par_id281641235880765">The string passed to the <literal>Val</literal> function is locale-independent. This means that commas are interpreted as thousands separators and a dot is used as the decimal separator.</note>
   </section>
   <embed href="text/sbasic/shared/00000003.xhp#functsyntax"/>
   <bascode>
@@ -40,16 +41,25 @@
   <embed href="text/sbasic/shared/00000003.xhp#functvalue"/>
   <paragraph id="par_id3143228" role="paragraph">Double</paragraph>
   <embed href="text/sbasic/shared/00000003.xhp#functparameters"/>
-  <paragraph id="par_id3154348" role="paragraph"> <emph>Text:</emph> String that represents a number.</paragraph>
-  <paragraph id="par_id3149670" role="paragraph">Using the Val function, you can convert a string that represents numbers into numeric expressions. This is the inverse of the <emph>Str</emph> function. If only part of the string contains numbers, only the first appropriate characters of the string are converted. If the string does not contain any numbers, the <emph>Val</emph> function returns the value 0.</paragraph>
+  <paragraph id="par_id3154348" role="paragraph"><emph>Text:</emph> String that represents a number.</paragraph>
+  <paragraph id="par_id3149670" role="paragraph">If only part of the string contains numbers, only the first appropriate characters of the string are converted. If the string does not contain any numbers then <literal>Val</literal> returns 0.</paragraph>
   <embed href="text/sbasic/shared/00000003.xhp#errorcode"/>
   <embed href="text/sbasic/shared/00000003.xhp#err5"/>
   <embed href="text/sbasic/shared/00000003.xhp#functexample"/>
   <bascode>
     <paragraph id="par_idm1341084240" role="bascode" localize="false">Sub ExampleVal</paragraph>
-    <paragraph id="par_idm1341083008" role="bascode" localize="false">    MsgBox Val("123.123")</paragraph>
-    <paragraph id="par_idm1341081760" role="bascode" localize="false">    MsgBox Val("A123.123")</paragraph>
+    <paragraph id="par_idm1341083008" role="bascode" localize="false">    MsgBox Val("123.1") + 1 ' 124.1</paragraph>
+    <paragraph role="bascode" id="bas_id131641236938068">    ' Below 123,1 is interpreted as 1231 since "," is the thousands separator</paragraph>
+    <paragraph id="par_idm1341083014" role="bascode" localize="false">    MsgBox Val("123,1") + 1 ' 1232</paragraph>
+    <paragraph role="bascode" id="bas_id681641252873197">    ' All numbers are considered until a non-numeric character is reached</paragraph>
+    <paragraph role="bascode" id="bas_id821641252904470" localize="false">    MsgBox Val("123.4A") ' 123.4</paragraph>
+    <paragraph role="bascode" id="bas_id911641237027667">    ' The example below returns 0 (zero) since the string provided does not start with a number</paragraph>
+    <paragraph id="par_idm1341081760" role="bascode" localize="false">    MsgBox Val("A123.123") ' 0</paragraph>
     <paragraph id="par_idm1341080512" role="bascode" localize="false">End Sub</paragraph>
   </bascode>
+
+  <section id="relatedtopics">
+    <embed href="text/sbasic/shared/03120103.xhp#Str_h1"/>
+  </section>
 </body>
 </helpdocument>