Convert-String has incorrect example

[zjalexander]

Issue Details

see #1236 : example #1 of convert-string.MD doesn't work

Convert-String -InputObject $Names -Example "Patti Fuller = Fuller, P."

Convert-String : Cannot convert 'System.Object[]' to the type 'System.String' required by parameter 'InputObject'.
Specified method is not supported.
At line:1 char:29
+ Convert-String -InputObject $Names -Example "Patti Fuller = Fuller, P ...
+                             ~~~~~~
    + CategoryInfo          : InvalidArgument: (:) [Convert-String], ParameterBindingException
    + FullyQualifiedErrorId : CannotConvertArgument,Microsoft.PowerShell.Commands.StringManipulation.ConvertStringComm
   and

'-InputObject' usually doesn't take a list, and you can't have blanks around the '=' sign.

PS> $Names | Convert-String -Example "Patti Fuller=Fuller, P."
Version(s) of document impacted

• Impacts 6 document
• Impacts 5.1 document
• Impacts 5.0 document
• Impacts 4.0 document
• Impacts 3.0 document

Reason(s) for not selecting all version of documents

• The documented feature was introduced in selected version of PowerShell
• This issue only shows up in selected version of the document

[juanpablojofre]

@zjalexander, @jszabo98,

I have to disagree with the suggested fix.

The syntax for Convert-String is:

Convert-String [-Example <System.Collections.Generic.List`1[System.Management.Automation.PSObject]>]
 -InputObject <String> [<CommonParameters>]

Which clearly states that -InputObject can take a simple string, not an array of strings. Hence, the error message of Cannot convert 'System.Object[]' to the type 'System.String' required by parameter 'InputObject'.

The reason why the following sample works:

"Mu Han", "Jim Hance", "David Ahs", "Kim Akers" | Convert-String -Example "Ed Wilson=Wilson, E."

Is because through the pipeline the array is converted to single elements that are PROCESSed by the Convert-String, one string at a time.

Best regards,
-- JP

[jszabo98]

I don't understand the disagreement? I agree that usually a -inputobject can only take one element while a pipe can take in a collection because of the process block in a function.

The text under example 1 needs to be cleaned up a bit, since there's only one command now:

"The first command creates an array that contains first and last names.
The second command formats the names according to the example. It puts the surname first in the output, followed by an initial."

By the way, under the '-example' parameter, it says:

"Patti Fuller = Fuller, P."

which won't work because of the spaces around the '=' sign.

[juanpablojofre]

@jszabo98,
If the issue is about the -InputObject argument not taking arrays, then the complain should be dropped. Because the BNF for this cmdlet clearly states that it takes no arrays, and the error message given is correct.

If the issue is about the description under the -Example heading, then a clarification needs to be made to indicate the string to the left of the = sign must be an exact match of the pattern elements.

This following code works pretty fine with the given example in the documentation.

$data = "Antonio Vivaldi 1678-1741", "Franz Liszt 1811-1886", "Dmitri Shostakovich 1906-1975", "JS Bach 1685-1750"
$data | Convert-String -Example "Patti Fuller = Fuller, P."

 Vivaldi, A.
 Liszt, F.
 Shostakovich, D.
 Bach, J.

Please note there is a leading space in each line of the output, as per the -Example.

[jszabo98]

I didn't say -inputobject should take an array. Example 1 originally demonstrated -inputobject taking an array.

I think most people would intend "Patti Fuller=Fuller, P.", as in example 1. Your example would be good to include as well. I don't think it's obvious that the spaces around the equal sign are part of the pattern.

[juanpablojofre]

@jszabo98,
Take a look into #1395 and let me know if you think this solves this issue.