[poe-commits] SF.net SVN: poe:[2490] trunk/poe/lib/POE/Filter.pm

[<rc...@us...>]

Revision: 2490
          http://poe.svn.sourceforge.net/poe/?rev=2490&view=rev
Author:   rcaputo
Date:     2009-03-02 20:52:40 +0000 (Mon, 02 Mar 2009)

Log Message:
-----------
Gcola discovered that we don't explain POE::Filter get() and get_one()
return values when there's nothing to return.

Modified Paths:
--------------
    trunk/poe/lib/POE/Filter.pm

Modified: trunk/poe/lib/POE/Filter.pm
===================================================================
--- 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.