local-lib5/lib/perl5/Data/Stream/Bulk/Util.pm

   1 #!/usr/bin/perl
   2
   3 package Data::Stream::Bulk::Util;
   4
   5 use strict;
   6 use warnings;
   7
   8 use Data::Stream::Bulk::Nil;
   9 use Data::Stream::Bulk::Array;
  10
  11 use Scalar::Util qw(refaddr);
  12
  13 use namespace::clean;
  14
  15 use Sub::Exporter -setup => {
  16         exports => [qw(nil bulk cat filter unique)],
  17 };
  18
  19 # use constant nil => Data::Stream::Bulk::Nil->new;
  20 sub nil () { Data::Stream::Bulk::Nil->new }
  21
  22 sub bulk (@) { return @_ ? Data::Stream::Bulk::Array->new( array => [ @_ ] ) : nil }
  23
  24 sub cat (@) { return @_ ? shift->cat(@_) : nil }
  25
  26 sub filter (&$) {
  27         my ( $filter, $stream ) = @_;
  28         $stream->filter($filter);
  29 }
  30
  31 sub unique ($) {
  32         my %seen;
  33         shift->filter(sub { [ grep { !$seen{ref($_) ? refaddr($_) : $_}++ } @$_ ] }); # FIXME Hash::Util::FieldHash::Compat::id()?
  34 }
  35
  36 __PACKAGE__
  37
  38 __END__
  39
  40 =pod
  41
  42 =head1 NAME
  43
  44 Data::Stream::Bulk::Util - Utility functions for L<Data::Stream::Bulk>
  45
  46 =head1 SYNOPSIS
  47
  48         use Data::Stream::Bulk::Util qw(array);
  49
  50         use namespace::clean;
  51
  52         # Wrap a list in L<Data::Stream::Bulk::Array>
  53         return bulk(qw(foo bar gorch baz));
  54
  55         # return an empty resultset
  56         return nil();
  57
  58 =head1 DESCRIPTION
  59
  60 This module exports convenience functions for use with L<Data::Stream::Bulk>.
  61
  62 =head1 EXPORTS
  63
  64 L<Sub::Exporter> is used to create the C<import> routine, and all of its
  65 aliasing/currying goodness is of course supported.
  66
  67 =over 4
  68
  69 =item nil
  70
  71 Creates a new L<Data::Stream::Bulk::Nil> object.
  72
  73 Takes no arguments.
  74
  75 =item bulk @items
  76
  77 Creates a new L<Data::Stream::Bulk::Array> wrapping C<@items>.
  78
  79 =item cat @streams
  80
  81 Concatenate several streams together.
  82
  83 Returns C<nil> if no arguments are provided.
  84
  85 =item filter { ... } $stream
  86
  87 Calls C<filter> on $stream with the provided filter.
  88
  89 =item unique $stream
  90
  91 Filter the stream to remove duplicates.
  92
  93 Note that memory use may potentially scale to O(k) where k is the number of
  94 distinct items, because this is implemented in terms of a seen hash.
  95
  96 In the future this will be optimized to be iterative for sorted streams.
  97
  98 References are keyed by their refaddr (see L<Hash::Util::FieldHash/id>).
  99
 100 =back
 101
 102 =cut
 103