StringScanner::search_full documentation error -?


#1
Meager as my Ruby skills are, I hesitate to claim to have found a documentation error, but I'm not sure what else to call it. I've looked for a ruby documentation list to report this to, and haven't found one, so I send it here.

At http://ruby-doc.org/core/, documentation for StringScanner::search_full reads -

"search_full(pattern, return_string_p, advance_pointer_p)

Scans the string until the pattern is matched. Returns the matched string if return_string_p is true, otherwise returns the number of bytes advanced. Advances the scan pointer if advance_pointer_p, otherwise not. This method does affect the match register."

But consider these (edited) results...

irb(main):005:0> a='abc .r def .n'                              
=> "abc .r def .n" 
irb(main):009:0> aa=StringScanner.new(a)
=> #<StringScanner 0/13 @ "abc ....">
irb(main):014:0> aa.search_full(/\.r /,true,false)
=> 7
irb(main):016:0> aa.pos
=> 7

[comment: these results are the opposite of what I expected - I did NOT get back the matched string, and the pointer WAS advanced.]

irb(main):021:0> aa.reset
=> #<StringScanner 0/13 @ "abc ....">
irb(main):022:0> aa.search_full(/\.r /,false,true)
=> "abc .r "
irb(main):023:0> aa.pos
=> 0

[comment: again - this is the opposite of what I expected, given the documentation.]

irb(main):025:0> a
=> "abc .r def .n"


Environment:
OS: Kubuntu Linux 8.10 Intrepid Ibix
/$ ruby -v
ruby 1.8.7 (2008-08-11 patchlevel 72) [i486-linux]

I've stared at these results for some minutes and don't yet see an "pilot error".

All comments welcome.

Tom
--
Tom C., MS MA, LMHC - Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
&lt;&lt; <a class="moz-txt-link-abbreviated" 
href="mailto:removed_email_address@domain.invalid">removed_email_address@domain.invalid</a> &gt;&gt; (email)
&lt;&lt; TomCloyd.com &gt;&gt; (website)
&lt;&lt; sleightmind.wordpress.com &gt;&gt; (mental health weblog)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~</pre>
</body>
</html>