+2
Not a bug

SUBSTRING function example poorly documented

Darren White 3 years ago updated by anonymous 3 years ago 3

The documentation for the SUBSTRING function is inconsistent, either incorrectly or poorly documented.


  • The EditSessionGroupPanel.Instructions text which is displayed when you press the Reference link in the Session Editor, as documented at https://docs.connectwise.com/ConnectWise_Control_Documentation/Get_started/Administration_page/Appearance_page/List_of_web_resource_strings
    has an incorrect description for the example of the SUBSTRING function.
    It incorrectly states: SUBSTRING(Name, 5, 4) = 'TEST': Sessions where characters 5-9 of the name are "TEST" (work-around for no wildcards in the middle)
    This suggests that characters 5,6,7,8 and 9 will be returned. The function example shown would actually only return characters 5-8. (4 characters returned, starting from character 5, returning characters 5,6,7,8)
  • The SUBSTRING function example in the documentation is available here: https://docs.connectwise.com/ConnectWise_Control_Documentation/Get_started/Host_page/Session_groups/Session_groups_filter_reference
    This explanation correctly shows that character number 9 will not be included. Here it is stated as:
    SUBSTRING(Name, 5, 4) = 'TEST' Sessions where characters 5 through 9 (not including 9) of the name are "TEST" (work-around for no wildcards in the middle)
    The current explanation is poor as stating that "characters .. through 9" is clearly inclusive of 9, and then 9 is stated as excluded (which contradicts the meaning of the term "through").

ConnectWise Control Version:
1
Server Affected:
Host Client Affected:
Guest Client Affected:

It has been suggested that the second explanation is correct, citing https://www.w3schools.com/jsref/jsref_substring.asp.

However this article is for the JavaScript Substring function.  (And is not official documentation for the JavaScript function standard or third party implementations) The JavaScript Substring function takes three parameters. The first is the string to process, the second is the starting position (which is a 0 based index), and the third is the ending position.
To extract the characters “test” (5-9) from the string “wordtesting” the Javascript substring call would be: substring(“wordtesting”,4,8).
The page also clearly states that the returned string consists of the characters that are BETWEEN the starting and ending position. BETWEEN is reasonable inclusive of the starting character, and exclusive of the ending character. It never uses the contradiction of saying that the returned string is THROUGH and is exclusive of an ending character index.


Some examples of documentation for functions that operate in the same way as Control's SUBSTRING:

  • The W3C XPath function “substring” standard (https://www.w3.org/TR/xpath-functions-31/#func-substring)
    W3C explains the function as:
    fn:substring(      $sourceString    as xs:string?, $start        as xs:double, $length    as xs:double) as xs:string
    The function returns a string comprising those ·characters·of $sourceString whose index position (counting from one) is greater than or equal to the value of $start (rounded to an integer), and (if $length is specified) less than the sum of $start and $length (both rounded to integers).
  • The Visual Basic MID Function (Microsoft VisualBasic - Strings - MID Function)
    Mid(String, Int32, Int32)                Returns a string that contains a specified number of characters starting from a specified position in a string.


+1
Planned

Good morning,


Thank you for submitting this report. I have registered an issue with development, and it's currently under review.


Cheers,

Ben

Commenting disabled