Boost C++ Libraries: Ticket #6596: Docs bug in boost_1_49_0_beta1/doc/html/boost/algorithm/find_head.html

owner, component changed

anonymous — Thu, 23 Feb 2012 08:26:13 GMT

owner changed from Matias Capeletto to Marshall Clow
component Documentation → algorithm

status, milestone changed

Marshall Clow — Thu, 23 Feb 2012 19:36:32 GMT

status new → assigned
milestone To Be Determined → Boost 1.50.0

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 — Thu, 23 Feb 2012 19:36:48 GMT

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

Thu, 23 Feb 2012 21:18:49 GMT

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 — Fri, 24 Feb 2012 21:32:02 GMT

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.

Sat, 25 Feb 2012 04:40:22 GMT

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 — Mon, 27 Feb 2012 20:29:07 GMT

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 — Mon, 27 Feb 2012 20:41:01 GMT

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

Mon, 27 Feb 2012 22:02:02 GMT

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?

status changed; resolution set

Marshall Clow — Wed, 23 May 2012 16:25:51 GMT

status assigned → closed
resolution → fixed

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