Bug 124066 - : Basic: missing Help for functions Replace and StrConv
Summary: : Basic: missing Help for functions Replace and StrConv
Status: ASSIGNED
Alias: None
Product: LibreOffice
Classification: Unclassified
Component: Documentation (show other bugs)
Version:
(earliest affected)
unspecified
Hardware: All All
: medium enhancement
Assignee: Olivier Hallot
URL:
Whiteboard: target:6.3.0
Keywords:
Depends on: 124184
Blocks: Macro-Documentation
  Show dependency treegraph
 
Reported: 2019-03-13 22:31 UTC by Gerhard Weydt
Modified: 2020-07-23 06:59 UTC (History)
3 users (show)

See Also:
Crash report or crash signature:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Gerhard Weydt 2019-03-13 22:31:57 UTC
For two functions available in Basic, namely Replace and StrConv, there is no help. These functions (as far as I understand, they were modelled upon eponymous functions in VBA) were introduced into OpenOffice.org and obviously also into LibreOffice (see https://bz.apache.org/ooo/show_bug.cgi?id=100953) as tentative, but they are still active, and at least the first one seems to be working completely. So, as some people already suggested, there should be a description in the help files, for they supply helpful functionality which would otherwise have to be programmed.
I supply descriptions that I hope can be used for the help files. In the first case I think it is complete, in the second case I provide a text which only covers the cases I could test, and a separate description of the rest where I am not sure what is happening.
For the second case, the function StrConv, there are could not get a convincing result regarding conversion from/to Unicode; hence I propose a text which may well be adjusted .
Especially, I am not sure whether a help text for StrConv should be published, as some functionality could not be verified by me, and the third parameter seems to be still irrelevant. Andrew Pitonyak provided some information in his OOME book, which could not be confirmed in the case of Unicode conversion, a situation which may well be outdated.


Replace Function
Replaces some string by another.

Syntax:
Replace (Text As String, SearchStr As String, ReplStr As String [, Start As Long [, Count as long [, Compare As Boolean]]]

Return Value:
String

Parameters:
Text: Any string expression that you want to modify.
SearchStr: Any string expression that shall be searched for.
ReplStr: Any string expression that shall replace the found search string.
Start: Numeric expression that indicates the character position within the string where the search shall begin. The maximum allowed value is 65535.
Count: The maximal number of times the replace shall be performed.
Compare: Optional numeric expression that defines the type of comparison. The value of this parameter can be 0 or 1. The default value of 1 specifies a text comparison that is not case-sensitive. The value of 0 specifies a binary comparison that is case-sensitive. You can as well use FALSE instead of 0 or TRUE instead of 1.

Error codes:
5 Invalid procedure call

Example:

msgbox replace ("aBbcnnbnn", "b", "$", 1, 1, FALSE)	'returns "aB$cnnbnn"
meaning: "b" should be replaced, but
    • only when lowercase (parameter 6), hence second occurrence of "b"
    • only first (respecting case) occurrence (parameter 5)


StrConvFunction
Converts a string according to the parameters supplied.

Syntax:
StrConv (Text As String, Mode As Long[, locale_id As Long ])

Return Value:
String

Parameters:
Text: Any string expression that you want to modify.
Mode: An integer (Long) value describing the type of conversion you want to be done:
0	No change.
1	Convert all characters to uppercase.
2	Convert all characters to lowercase.
3	Convert first characters of each word to uppercase.
4	Convert narrow (half-width) characters in the string to wide (full-width) characters.
8	Convert wide (full-width) characters in the string to narrow (half-width) characters.
16	Convert Hiragana characters in the string to Katakana characters.
32	Convert Katakana characters in the string to Hiragana characters.
Modes 4 and 8 are mainly applicable to Far East character sets; Modes 16 and 32 are used for Japanese character sets

Error codes:
5 Invalid procedure call

Example:

msgbox StrConv("abb jkk",3)	'returns "Abb Jkk"


Additional information for StrConv, to be added in some form to the above help only if found to be correct:
The description for the following values of parameter “mode” as found in Andrew Pitonyak’s OOME is not very clear: 
64	Convert all characters to Unicode.
128	Convert all characters from Unicode.
The following explanation is derived from Microsoft’s function:
64	Converts the string to Unicode using the default code page of the system.
128	Converts the string from Unicode to the default code page of the system.
The output of a call with mode 128 is for my system an array of bytes, and according to information found somewhere in the Microsoft files, it should be an array of multiple bytes for other codepages, e.g. asian ones. Such an array can be used as input for a call with mode 64. It seems to me that the description derived from the Microsoft function applies to the LibreOffice function, but then I could only test it with the codepage used in Germany (which is probably 1252). I am not able to test these modes in other situations.
One reason not to mention the modes 64 and 128 might also be that there may possibly not much need now for them, as Unicode is prevalent.
Comment 1 Olivier Hallot 2019-03-14 10:55:55 UTC
For information:

StrConv seems to be VBA-only function.

A QA test of the current implementation is available in

https://opengrok.libreoffice.org/xref/core/basic/qa/vba_tests/strconv.vb?r=b9d75dea

The commented tests obvioulsy fails and were nuked to prevent build break.
Comment 2 Commit Notification 2019-03-14 14:58:00 UTC
Olivier Hallot committed a patch related to this issue.
It has been pushed to "master":

https://git.libreoffice.org/help/+/e6dfe7b36ebfda217fe89c18b656d2eee72c18ce%5E%21

tdf#124066, tdf#114263 BASIC Replace function Help
Comment 3 Gerhard Weydt 2019-03-14 23:32:32 UTC
(In reply to Olivier Hallot from comment #1)
> For information:
> 
> StrConv seems to be VBA-only function.
> 
> A QA test of the current implementation is available in
> 
> https://opengrok.libreoffice.org/xref/core/basic/qa/vba_tests/strconv.
> vb?r=b9d75dea
> 
> The commented tests obvioulsy fails and were nuked to prevent build break.

I've had a closer look at the QA test program and I must say, it leaves some serious questions:

for a start, only a minor question: VBA support is only needed when using the constants vb...; using the numbers (the only information I had when testing, based on Andrew Pitonyak's OOME) the code works correctly.

The errorHandler contains two problems:

The string ...(False)... in the first line causes a syntax error: the opening bracket is obviously interpreted as preceding the parameters of the function, and then the part nafter the closing bracket does not confirm to the syntax rules. The code runs correctly if the brackets are left out or if the closing bracket is moved to the end of the line.

The line "verify_testStrConv = result" is missing in the errorHandler. Hence, the correct value assigned to the variable "result" is overwritten by the first statement of doUnitTest, where the return value of verify_testStrConv still is an empty string.

Now to the tests in verify_testStrConv:

For the conversion to "wide" the string used for comparison has nothing to do with the actual result: The string presented by msgbox is: "ABCDEVB¥ì¥¹¥­¥å©`". Using this for comparison yields an OK.
But using this as input for the conversion to narrow doesn't work. Obviously there are some limitations for strings to be entered in Basic.
Using the output of the conversion to wide, though, directly as input for the conversion to narrow, does work.
I tested this by reading and replacing the content of a test document, where support of fonts is given, and it worked perfecty.

Probaly the same applies to the conversion between Hiragana/Katagana: the conversion works fine when randomly chosen characters out of the Hiragana range and back again; but I don't understand the strings used in the QA program.

Conversion from/to Unicode works in my constellation, too. But this is a simple, European situation.

Conclusions:
Help for modes up to 3 could be safey published.
For modes up to 32 the function seems to work correctly, but the test code ha to be adjusted, if it should be activated (which should be desirable, otherwise it would be useless).
For modes 64 and 128 the code seems to me correct, but I can only test the quite simple case of a european installation.
Someone with a deeper knowledge of codepages and string representations should hav a ookat it.
Comment 4 Olivier Hallot 2019-03-18 21:46:39 UTC
Until the QA test is implemented and validates StrConv(), it is not advisable to publish any documentation of the function. It can lead to errors and expose issues on quality.

Therefore I am making this bug dependent of bug#124184.
Comment 5 Mike Kaganski 2020-07-23 06:59:25 UTC
StrConv in LO does not implement handling its third argument (LCID). Without that, there's no way to create useful unit tests (since everything is system-dependent, and so different on different systems).

If someone wants to implement that, the code is SbRtl_StrConv in basic/source/runtime/methods.cxx; LCIDs (MS thing [1]) is represented in LO by LanguageType (include/i18nlangtag/lang.h), so it's directly usable in the SbRtl_StrConv function, that also internally uses a LanguageType value hardcoded to LANGUAGE_SYSTEM.

[1] https://msdn.microsoft.com/en-us/goglobal/bb964664