Measure-Object: fix the description of -Property, clarify the relationship between -Line, -Char, -Word and -Property #4062

The -Property parameter is described as follows in the Measure-Object topic:

Specifies one or more numeric properties to measure. The default is the Count property of the object.

• This is confusing: Count comes into play not as a property on the input objects, but as the property that is populated by default in the output object; in other words: the (only) default measuring action performed on the inputs is to count them, and counting is unrelated to what you specify in -Property - even if the property values happen to be collections themselves (see this related feature request: Add a -Recurse switch to Measure-Object to support input objects / properties that are collections themselves PowerShell/PowerShell#7244).

  • The only exception are input objects that do not have the specified property/ies: they are quietly excluded from the count.
  • On a related note, it is worth mentioning that only one object among all input object is required to have the properties specified with -Property and that all objects without them are ignored, which affects not only the reported count, but also count-based measurements, namely -Average.

• Also, if you combine -Property with any of the -Line, -Char, and -Word switches, doing so only makes sense if the specified properties are strings, so -Property isn't just about numeric properties.

• It would also be helpful to clarify that the -Line, -Char, and -Word switches count inside each input object (string) as well as across objects, with each object implicitly considered (at least) 1 line; for instance, the following commands all yield the same line count of 3:

'one', 'two', 'three' | Measure-Object -Line # -> 3
"one`ntwo`nthree" | Measure-Object -Line # -ditto
'one', "two`nthree" | Measure-Object -Line # -ditto

The switch descriptions currently suggest that there's only a single input object (string); e.g., for -Line (emphasis added):

Indicates that the cmdlet counts the number of lines in the input object.

While it makes sense to use a single, multi-line string with these switches, note that the current
-Line example passes an array of lines - due to using Get-Content without -Raw, which, however, is preferable for large files, due to line-by-line processing:

Example 3: Measure text in a text file
Get-Content C:\test.txt | Measure-Object -Character -Line -Word

However, for -Character to be accurate, passing a multiline string as a single input is a must:

"a`nb" | Measure-Object -Char # -> 3
'a', 'b' | Measure-Object -Char # -> !! 2

Version(s) of document impacted

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