Date: 2009-03-02 20:52:40 +0000 (Mon, 02 Mar 2009)
Gcola discovered that we don't explain POE::Filter get() and get_one()
return values when there's nothing to return.
--- trunk/poe/lib/POE/Filter.pm 2009-03-02 20:19:54 UTC (rev 2489)
+++ trunk/poe/lib/POE/Filter.pm 2009-03-02 20:52:40 UTC (rev 2490)
@@ -166,14 +166,16 @@
get_one() parses zero or one complete item from the filter's internal
buffer. The data is returned as an ARRAYREF suitable for passing to
-another filter or a POE::Wheel object.
+another filter or a POE::Wheel object. Filters will return empty
+ARRAYREFs if they don't have enough raw data to build a complete item.
get_one() is the lazy form of get(). It only parses only one item at
a time from the filter's buffer. This is vital for applications that
may switch filters in mid-stream, as it ensures that the right filter
is in use at any given time.
-The L</SYNOPSIS> shows get_one() in use.
+The L</SYNOPSIS> shows get_one() in use. Note how it assumes the
+return is always an ARRAYREF, and it implicitly handles empty ones.
=head2 get ARRAYREF
@@ -183,6 +185,9 @@
possible from the buffer and returns them in another array reference.
Any unprocessed data remains in the filter's buffer for the next call.
+As with get_one(), get() will return an empty array reference if the
+filter doesn't contain enough raw data to build a complete item.
In fact, get() is implemented in POE::Filter in terms of
get_one_start() and get_one().
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.