Docs bug in boost_1_49_0_beta1/doc/html/boost/algorithm/find_head.html

[Michael J Smith <emmenjay@…>]

There is a typo in the description:

... whole input if considered to be the head.

The word if should be is.

In fact the whole description could be made clearer. I suggest the following:

Get the first 'N' elements of the range 'input'. If 'input' is less than 'N' elements long, return the whole range.

[Marshall Clow]

Thanks for the bug report.

At first I really liked your suggestion, but when I looked more closely, I noticed that both find_head and find_tail can take negative length parameters (N) which mean return length(input)+N , so I think that the statement "If 'input' is less than 'N' elements long" is not correct.

I checked in the minimal change (if/is), and will think about a better way to word this.

[Marshall Clow]

(In [77101]) Fix typos; Refs #6596

[Michael J Smith <emmenjay@…>]

Replying to marshall:

Thanks for the bug report.

At first I really liked your suggestion, but when I looked more closely, I noticed that both find_head and find_tail can take negative length parameters (N) which mean return length(input)+N , so I think that the statement "If 'input' is less than 'N' elements long" is not correct.

I checked in the minimal change (if/is), and will think about a better way to word this.

Oops. Post in haste, repent at leisure.

How about this:

For 'N' >= 0: Get the first 'N' elements of the input range. If 'N' is greater than the length of the input range, return the whole input range.

For 'N' < 0: Get the first size(input) + 'N' elements.

e.g.

    string s = "Algorithm";
    FindHead(s, 3);   // returns "Alg"
    FindHead(s, 42);  // returns "Algorithm"
    FindHead(s, -3);  // returns "Algori"

[anonymous]

I'm looking at the page some more, and I see:

Description:  Get the head of the input. 
            Head is a prefix of the string of the given size. 
            If the input is shorter then required, 
                       whole input is considered to be the head.
...
Parameters:
Input:An input string
N: Length of the head 
      For N>=0, at most N characters are extracted. 
      For N<0, size(Input)-|N| characters are extracted.

I think adding "at most" before "size(Input)" needs to be done. As for the description, I think putting the length semantics there is a duplication.

Hmm.

[Michael J Smith <emmenjay@…>]

Replying to anonymous:

As for the description, I think putting the length semantics there is a duplication.

You may be right. Let me give you some context. I've just started messing with Boost and had no idea what find_head() did. I brought up the docs and looked at the prototype, then read the description. I had to puzzle over the description for a couple of minutes to figure out what it meant. I figured that there might be a clearer way of saying it.

Talking of a "string" in the description is potentially confusing as the input range doesn't have to be a string.

In that context, "prefix" is not entirely clear.

I guess I'd like to see a phrase containing something like "the first 'N' elements of the input range" in there somewhere.

Thoughts?

[anonymous]

I guess I'd like to see a phrase containing something like "the first 'N' elements of the input range" in there somewhere.

I specifically don't want to say that - because it isn't true (in general).

It is true only when N is >= 0 and < length of the input sequence.

What I was trying to say in my earlier comment (about duplication) is that the semantics for positive and negative values of N are right there on the page - but not in the description.

I'm not opposed to changing the description; I just want to find something better.

[Marshall Clow]

(In [77130]) Another doc fix; Refs #6596

[Michael J Smith <emmenjay@…>]

Replying to anonymous:

I'm not opposed to changing the description; I just want to find something better.

I fear that I may be turning into a pest and that's not my intention. I'm just tossing up some ideas for your consideration, I'm not strongly attached to any particular position.

Your point about duplication is well made so I won't say more about that.

What do you think about my point about the terms "string" and "prefix"? Do you think they may be misleading, given the flexibility of the "input range" to contain other data types, or do you see "string" input ranges as being the main event?

[Marshall Clow]

(In [78557]) Merged changes for Boost.Algorithm to release; Fixes #6596; Fixes #6689; Fixes #3215; Fixes #6840