Merge pull request #1360 from mojolicious/collection_head_tail

head and tail methods for Mojo::Collection

lib/Mojo/Collection.pm

@@ -43,6 +43,13 @@ sub grep {
   return $self->new(grep { $_->$cb(@_) } @$self);
 }
 
+sub head {
+  my ($self, $size) = @_;
+  return $self->new(@$self) if $size > @$self;
+  return $self->new(@$self[0 .. ($size - 1)]) if $size >= 0;
+  return $self->new(@$self[0 .. ($#$self + $size)]);
+}
+
 sub join {
   Mojo::ByteStream->new(join $_[1] // '', map {"$_"} @{$_[0]});
 }
@@ -92,6 +99,13 @@ sub sort {
   return $self->new(@sorted);
 }
 
+sub tail {
+  my ($self, $size) = @_;
+  return $self->new(@$self) if $size > @$self;
+  return $self->new(@$self[($#$self - ($size - 1)) .. $#$self]) if $size >= 0;
+  return $self->new(@$self[(0 - $size) .. $#$self]);
+}
+
 sub tap { shift->Mojo::Base::tap(@_) }
 
 sub to_array { [@{shift()}] }
@@ -247,6 +261,20 @@ C<$_>.
   # Find all values that are greater than 5
   my $greater = $collection->grep(sub { $_ > 5 });
 
+=head2 head
+
+  my $new = $collection->head(4);
+  my $new = $collection->head(-2);
+
+Create a new collection with up to the specified number of elements from the
+beginning of the collection. A negative number will count from the end.
+
+  # "A B C"
+  c('A', 'B', 'C', 'D', 'E')->head(3)->join(' ');
+
+  # "A B"
+  c('A', 'B', 'C', 'D', 'E')->head(-3)->join(' ');
+
 =head2 join
 
   my $stream = $collection->join;
@@ -332,6 +360,20 @@ time the callback is executed.
   # Sort values case-insensitive
   my $case_insensitive = $collection->sort(sub { uc($a) cmp uc($b) });
 
+=head2 tail
+
+  my $new = $collection->tail(4);
+  my $new = $collection->tail(-2);
+
+Create a new collection with up to the specified number of elements from the
+end of the collection. A negative number will count from the beginning.
+
+  # "C D E"
+  c('A', 'B', 'C', 'D', 'E')->tail(3)->join(' ');
+
+  # "D E"
+  c('A', 'B', 'C', 'D', 'E')->tail(-3)->join(' ');
+
 =head2 tap
 
   $collection = $collection->tap(sub {...});

t/mojo/collection.t

@@ -163,4 +163,28 @@ is_deeply $collection->uniq(sub {$_})->to_array, [undef, 3, 2, 1, 0],
 # TO_JSON
 is encode_json(c(1, 2, 3)), '[1,2,3]', 'right result';
 
+# head
+$collection = c(1, 2, 5, 4, 3);
+is_deeply $collection->head(0)->to_array, [], 'right result';
+is_deeply $collection->head(1)->to_array, [1], 'right result';
+is_deeply $collection->head(2)->to_array, [1, 2], 'right result';
+is_deeply $collection->head(-1)->to_array, [1, 2, 5, 4], 'right result';
+is_deeply $collection->head(-3)->to_array, [1, 2], 'right result';
+is_deeply $collection->head(5)->to_array, [1, 2, 5, 4, 3], 'right result';
+is_deeply $collection->head(6)->to_array, [1, 2, 5, 4, 3], 'right result';
+is_deeply $collection->head(-5)->to_array, [], 'right result';
+is_deeply $collection->head(-6)->to_array, [], 'right result';
+
+# tail
+$collection = c(1, 2, 5, 4, 3);
+is_deeply $collection->tail(0)->to_array, [], 'right result';
+is_deeply $collection->tail(1)->to_array, [3], 'right result';
+is_deeply $collection->tail(2)->to_array, [4, 3], 'right result';
+is_deeply $collection->tail(-1)->to_array, [2, 5, 4, 3], 'right result';
+is_deeply $collection->tail(-3)->to_array, [4, 3], 'right result';
+is_deeply $collection->tail(5)->to_array, [1, 2, 5, 4, 3], 'right result';
+is_deeply $collection->tail(6)->to_array, [1, 2, 5, 4, 3], 'right result';
+is_deeply $collection->tail(-5)->to_array, [], 'right result';
+is_deeply $collection->tail(-6)->to_array, [], 'right result';
+
 done_testing();