File Coverage

blib/lib/Sub/HandlesVia/HandlerLibrary/Array.pm

Criterion	Covered	Total	%
statement	198	202	98.0
branch	17	20	85.0
condition	19	30	63.3
subroutine	92	93	98.9
pod	61	61	100.0
total	387	406	95.3

use 5.008;
use strict;
use warnings;


our $AUTHORITY = 'cpan:TOBYINK';
our $VERSION   = '0.045';

use Sub::HandlesVia::HandlerLibrary;
our @ISA = 'Sub::HandlesVia::HandlerLibrary';

use Sub::HandlesVia::Handler qw( handler );
use Types::Standard qw( ArrayRef Optional Str CodeRef Int Item Any Ref Defined FileHandle );

our @METHODS = qw( count is_empty all elements flatten get pop push shift
	unshift clear first first_index reduce set accessor natatime any
	shallow_clone map grep sort reverse sort_in_place splice shuffle
	shuffle_in_place uniq uniq_in_place delete insert flatten flatten_deep
	join print head tail apply pick_random for_each for_each_pair
	all_true not_all_true min minstr max maxstr sum product
	reductions sample uniqnum uniqnum_in_place uniqstr uniqstr_in_place
	pairs pairkeys pairvalues pairgrep pairfirst pairmap reset );

	my ($me, $type) = @_;
	if ($type == ArrayRef or $type == Defined or $type == Ref) {
		return {
			trust_mutated => 'always',
		};
	}
	if ($type->is_parameterized
	and $type->parent->name eq 'ArrayRef'
	and $type->parent->library eq 'Types::Standard'
	and 1==@{$type->parameters}) {
		return {
			trust_mutated => 'maybe',
			value_type    => $type->type_parameter,
		};
	}
	return $me->SUPER::_type_inspector($type);
}

my $additional_validation_for_push_and_unshift = sub {
	my $self = CORE::shift;
	my ($sig_was_checked, $gen) = @_;
	my $ti = __PACKAGE__->_type_inspector($gen->isa);

	if ($ti and $ti->{trust_mutated} eq 'always') {
		return { code => '1;', env => {} };
	}

	if ($ti and $ti->{trust_mutated} eq 'maybe') {
		my $coercion = ( $gen->coerce and $ti->{value_type}->has_coercion );
		if ( $coercion ) {
			my $env = {};
			my $code = sprintf(
				'my @shv_values = map { my $shv_value = $_; %s } %s;',
				$gen->generate_type_assertion( $env, $ti->{value_type}, '$shv_value' ),
				$gen->generate_args,
			);
			return {
				code      => $code,
				env       => $env,
				arg       => sub { "\$shv_values[($_[0])-1]" },
				args      => sub { '@shv_values' },
				argc      => sub { 'scalar(@shv_values)' },
			};
		}
		else {
			my $env = {};
			my $code = sprintf(
				'for my $shv_value (%s) { %s }',
				$gen->generate_args,
				$gen->generate_type_assertion( $env, $ti->{value_type}, '$shv_value' ),
			);
			return {
				code      => $code,
				env       => $env,
			};
		}
	}
	return;
};

my $additional_validation_for_set_and_insert = sub {
	my $self = CORE::shift;
	my ($sig_was_checked, $gen) = @_;
	my $ti = __PACKAGE__->_type_inspector($gen->isa);

	if ($ti and $ti->{trust_mutated} eq 'always') {
		return { code => '1;', env => {} };
	}

	my ( $arg, $code, $env );
	$env = {};
	if ($ti and $ti->{trust_mutated} eq 'maybe') {
		$arg = sub {
			my $gen = CORE::shift;
			return '$shv_index' if $_[0]=='1';
			return '$shv_value' if $_[0]=='2';
			$gen->generate_arg( @_ );
		};
		if ( $sig_was_checked ) {
			$code = sprintf(
				'my($shv_index,$shv_value)=%s; %s;',
				$gen->generate_args,
				$gen->generate_type_assertion( $env, $ti->{value_type}, '$shv_value' ),
			);
		}
		else {
			$code = sprintf(
				'my($shv_index,$shv_value)=%s; %s; %s;',
				$gen->generate_args,
				$gen->generate_type_assertion( $env, Int, '$shv_index' ),
				$gen->generate_type_assertion( $env, $ti->{value_type}, '$shv_value' ),
			);
		}
	}
	return {
		code      => $code,
		env       => $env,
		arg       => $arg,
	};
};

	handler
		name      => 'Array:count',
		args      => 0,
		template  => 'scalar(@{$GET})',
		documentation => 'The number of elements in the referenced array.',
		_examples => sub {
			my ( $class, $attr, $method ) = @_;
			return CORE::join "",
				"  my \$object = $class\->new( $attr => [ 'foo', 'bar' ] );\n",
				"  say \$object->$method; ## ==> 2\n",
				"\n";
		},
}

	handler
		name      => 'Array:is_empty',
		args      => 0,
		template  => '!scalar(@{$GET})',
		documentation => 'Boolean indicating if the referenced array is empty.',
		_examples => sub {
			my ( $class, $attr, $method ) = @_;
			return CORE::join "",
				"  my \$object = $class\->new( $attr => [ 'foo', 'bar' ] );\n",
				"  say \$object->$method; ## ==> false\n",
				"  \$object->_set_$attr( [] );\n",
				"  say \$object->$method; ## ==> true\n",
				"\n";
		},
}

	handler
		name      => 'Array:all',
		args      => 0,
		template  => '@{$GET}',
		documentation => 'All elements in the array, in list context.',
		_examples => sub {
			my ( $class, $attr, $method ) = @_;
			return CORE::join "",
				"  my \$object = $class\->new( $attr => [ 'foo', 'bar' ] );\n",
				"  my \@list = \$object->$method;\n",
				"  say Dumper( \\\@list ); ## ==> [ 'foo', 'bar' ]\n",
				"\n";
		},
}

	handler
		name      => 'Array:elements',
		args      => 0,
		template  => '@{$GET}',
		documentation => 'All elements in the array, in list context. (Essentially the same as C<all>.)',
		_examples => sub {
			my ( $class, $attr, $method ) = @_;
			return CORE::join "",
				"  my \$object = $class\->new( $attr => [ 'foo', 'bar' ] );\n",
				"  my \@list = \$object->$method;\n",
				"  say Dumper( \\\@list ); ## ==> [ 'foo', 'bar' ]\n",
				"\n";
		},
}

	handler
		name      => 'Array:flatten',
		args      => 0,
		template  => '@{$GET}',
		documentation => 'All elements in the array, in list context. (Essentially the same as C<all>.)',
		_examples => sub {
			my ( $class, $attr, $method ) = @_;
			return CORE::join "",
				"  my \$object = $class\->new( $attr => [ 'foo', 'bar' ] );\n",
				"  my \@list = \$object->$method;\n",
				"  say Dumper( \\\@list ); ## ==> [ 'foo', 'bar' ]\n",
				"\n";
		},
}

	handler
		name      => 'Array:get',
		args      => 1,
		signature => [Int],
		usage     => '$index',
		template  => '($GET)->[$ARG]',
		documentation => 'Returns a single element from the array by index.',
		_examples => sub {
			my ( $class, $attr, $method ) = @_;
			return CORE::join "",
				"  my \$object = $class\->new( $attr => [ 'foo', 'bar', 'baz' ] );\n",
				"  say \$object->$method(  0 ); ## ==> 'foo'\n",
				"  say \$object->$method(  1 ); ## ==> 'bar'\n",
				"  say \$object->$method( -1 ); ## ==> 'baz'\n",
				"\n";
		},
}

	my $me = CORE::shift;
	handler
		name      => 'Array:pop',
		args      => 0,
		template  => 'my @shv_tmp = @{$GET}; my $shv_return = pop @shv_tmp; «\\@shv_tmp»; $shv_return',
		lvalue_template => 'pop(@{$GET})',
		additional_validation => 'no incoming values',
		documentation => 'Removes the last element from the array and returns it.',
		_examples => sub {
			my ( $class, $attr, $method ) = @_;
			return CORE::join "",
				"  my \$object = $class\->new( $attr => [ 'foo', 'bar', 'baz' ] );\n",
				"  say \$object->$method; ## ==> 'baz'\n",
				"  say \$object->$method; ## ==> 'bar'\n",
				"  say Dumper( \$object->$attr ); ## ==> [ 'foo' ]\n",
				"\n";
		},
}

	my $me = CORE::shift;
	handler
		name      => 'Array:push',
		usage     => '@values',
		template  => 'my @shv_tmp = @{$GET}; my $shv_return = push(@shv_tmp, @ARG); «\\@shv_tmp»; $shv_return',
		lvalue_template => 'push(@{$GET}, @ARG)',
		prefer_shift_self => 1,
		additional_validation => $additional_validation_for_push_and_unshift,
		documentation => 'Adds elements to the end of the array.',
		_examples => sub {
			my ( $class, $attr, $method ) = @_;
			return CORE::join "",
				"  my \$object = $class\->new( $attr => [ 'foo' ] );\n",
				"  \$object->$method( 'bar', 'baz' );\n",
				"  say Dumper( \$object->$attr ); ## ==> [ 'foo', 'bar', 'baz' ]\n",
				"\n";
		},
}

	my $me = CORE::shift;
	handler
		name      => 'Array:shift',
		args      => 0,
		template  => 'my @shv_tmp = @{$GET}; my $shv_return = shift @shv_tmp; «\\@shv_tmp»; $shv_return',
		lvalue_template => 'shift(@{$GET})',
		additional_validation => 'no incoming values',
		documentation => 'Removes an element from the start of the array and returns it.',
		_examples => sub {
			my ( $class, $attr, $method ) = @_;
			return CORE::join "",
				"  my \$object = $class\->new( $attr => [ 'foo', 'bar', 'baz' ] );\n",
				"  say \$object->$method; ## ==> 'foo'\n",
				"  say \$object->$method; ## ==> 'bar'\n",
				"  say Dumper( \$object->$attr ); ## ==> [ 'baz' ]\n",
				"\n";
		},
}

	my $me = CORE::shift;
	handler
		name      => 'Array:unshift',
		usage     => '@values',
		template  => 'my @shv_tmp = @{$GET}; my $shv_return = unshift(@shv_tmp, @ARG); «\\@shv_tmp»; $shv_return',
		lvalue_template => 'unshift(@{$GET}, @ARG)',
		prefer_shift_self => 1,
		additional_validation => $additional_validation_for_push_and_unshift,
		documentation => 'Adds an element to the start of the array.',
		_examples => sub {
			my ( $class, $attr, $method ) = @_;
			return CORE::join "",
				"  my \$object = $class\->new( $attr => [ 'foo' ] );\n",
				"  \$object->$method( 'bar', 'baz' );\n",
				"  say Dumper( \$object->$attr ); ## ==> [ 'bar', 'baz', 'foo' ]\n",
				"\n";
		},
}

	my $me = CORE::shift;
	handler
		name      => 'Array:clear',
		args      => 0,
		template  => '«[]»',
		lvalue_template => '@{$GET} = ()',
		additional_validation => 'no incoming values',
		documentation => 'Empties the array.',
		_examples => sub {
			my ( $class, $attr, $method ) = @_;
			return CORE::join "",
				"  my \$object = $class\->new( $attr => [ 'foo' ] );\n",
				"  \$object->$method;\n",
				"  say Dumper( \$object->$attr ); ## ==> []\n",
				"\n";
		},
}

	require List::Util;
	handler
		name      => 'Array:first',
		args      => 1,
		signature => [CodeRef],
		usage     => '$coderef',
		template  => '&List::Util::first($ARG, @{$GET})',
		documentation => 'Like C<< List::Util::first() >>.',
		_examples => sub {
			my ( $class, $attr, $method ) = @_;
			return CORE::join "",
				"  my \$object = $class\->new( $attr => [ 'foo', 'bar', 'baz' ] );\n",
				"  my \$found  = \$object->$method( sub { /a/ } );\n",
				"  say \$found; ## ==> 'bar'\n",
				"\n";
		},
}

	require List::Util;
	handler
		name      => 'Array:any',
		args      => 1,
		signature => [CodeRef],
		usage     => '$coderef',
		template  => '&List::Util::any($ARG, @{$GET})',
		documentation => 'Like C<< List::Util::any() >>.',
		_examples => sub {
			my ( $class, $attr, $method ) = @_;
			return CORE::join "",
				"  my \$object = $class\->new( $attr => [ 'foo', 'bar', 'baz' ] );\n",
				"  my \$truth  = \$object->$method( sub { /a/ } );\n",
				"  say \$truth; ## ==> true\n",
				"\n";
		},
}

	my $me = __PACKAGE__;
	handler
		name      => 'Array:first_index',
		args      => 1,
		signature => [CodeRef],
		usage     => '$coderef',
		template  => 'for my $i ( 0 .. $#{$GET} ) { local *_ = \$GET->[$i]; return $i if $ARG->($_) }; return -1;',
		documentation => 'Like C<< List::MoreUtils::first_index() >>.',
		_examples => sub {
			my ( $class, $attr, $method ) = @_;
			return CORE::join "",
				"  my \$object = $class\->new( $attr => [ 'foo', 'bar', 'baz' ] );\n",
				"  my \$found  = \$object->$method( sub { /z\$/ } );\n",
				"  say \$found; ## ==> 2\n",
				"\n";
		},
}

	require List::Util;
	handler
		name      => 'Array:reduce',
		args      => 1,
		signature => [CodeRef],
		usage     => '$coderef',
		template  => 'my $shv_callback = $ARG; List::Util::reduce { $shv_callback->($a,$b) } @{$GET}',
		documentation => 'Like C<< List::Util::reduce() >>.',
}

	my $me = CORE::shift;
	handler
		name      => 'Array:set',
		args      => 2,
		signature => [Int, Any],
		usage     => '$index, $value',
		template  => 'my @shv_tmp = @{$GET}; $shv_tmp[$ARG[1]] = $ARG[2]; «\\@shv_tmp»; $ARG[2]',
		lvalue_template => '($GET)->[ $ARG[1] ] = $ARG[2]',
		additional_validation => $additional_validation_for_set_and_insert,
		documentation => 'Sets the element with the given index to the supplied value.',
		_examples => sub {
			my ( $class, $attr, $method ) = @_;
			return CORE::join "",
				"  my \$object = $class\->new( $attr => [ 'foo', 'bar', 'baz' ] );\n",
				"  \$object->$method( 1, 'quux' );\n",
				"  say Dumper( \$object->$attr ); ## ==> [ 'foo', 'quux', 'baz' ]\n",
				"\n";
		},
}

	handler
		name      => 'Array:accessor',
		min_args  => 1,
		max_args  => 2,
		signature => [Int, Optional[Any]],
		usage     => '$index, $value?',
		template  => 'if (#ARG == 1) { ($GET)->[ $ARG[1] ] } else { my @shv_tmp = @{$GET}; $shv_tmp[$ARG[1]] = $ARG[2]; «\\@shv_tmp»; $ARG[2] }',
		lvalue_template => '(#ARG == 1) ? ($GET)->[ $ARG[1] ] : (($GET)->[ $ARG[1] ] = $ARG[2])',
		additional_validation => sub {
			my $self = CORE::shift;
			my ($sig_was_checked, $gen) = @_;
			my $ti = __PACKAGE__->_type_inspector($gen->isa);
			if ($ti and $ti->{trust_mutated} eq 'always') {
				return { code => '1;', env => {} };
			}
			my ( $code, $env, $arg );
			$env = {};
			if ($ti and $ti->{trust_mutated} eq 'maybe') {
				$arg = sub {
					my $gen = CORE::shift;
					return '$shv_index' if $_[0]=='1';
					return '$shv_value' if $_[0]=='2';
					$gen->generate_arg( @_ );
				};
				if ( $sig_was_checked ) {
					$code = sprintf(
						'my($shv_index,$shv_value)=%s; if (%s>1) { %s };',
						$gen->generate_args,
						$gen->generate_argc,
						$gen->generate_type_assertion( $env, $ti->{value_type}, '$shv_value' ),
					);
				}
				else {
					$code = sprintf(
						'my($shv_index,$shv_value)=%s; %s; if (%s>1) { %s };',
						$gen->generate_args,
						$gen->generate_type_assertion( $env, Int, '$shv_index' ),
						$gen->generate_argc,
						$gen->generate_type_assertion( $env, $ti->{value_type}, '$shv_value' ),
					);
				}
			}
			return {
				code => $code,
				env => $env,
				arg => $arg,
			};
		},
	documentation => 'Acts like C<get> if given just an index, or C<set> if given an index and value.',
	_examples => sub {
		my ( $class, $attr, $method ) = @_;
		return CORE::join "",
			"  my \$object = $class\->new( $attr => [ 'foo', 'bar', 'baz' ] );\n",
			"  \$object->$method( 1, 'quux' );\n",
			"  say Dumper( \$object->$attr ); ## ==> [ 'foo', 'quux', 'baz' ]\n",
			"  say \$object->$method( 2 ); ## ==> 'baz'\n",
			"\n";
	},
}

	my $me = __PACKAGE__;
	handler
		name      => 'Array:natatime',
		min_args  => 1,
		max_args  => 2,
		signature => [Int, Optional[CodeRef]],
		usage     => '$n, $callback?',
		template  => 'my @shv_remaining = @{$GET}; my $shv_n = $ARG[1]; my $shv_iterator = sub { CORE::splice @shv_remaining, 0, $shv_n }; if ($ARG[2]) { while (my @shv_values = $shv_iterator->()) { $ARG[2]->(@shv_values) } } else { $shv_iterator }',
		documentation => 'Given just a number, returns an iterator which reads that many elements from the array at a time. If also given a callback, calls the callback repeatedly with those values.',
		_examples => sub {
			my ( $class, $attr, $method ) = @_;
			return CORE::join "",
				"  my \$object = $class\->new( $attr => [ 'foo', 'bar', 'baz' ] );\n",
				"  my \$iter   = \$object->$method( 2 );\n",
				"  say Dumper( [ \$iter->() ] ); ## ==> [ 'foo', 'bar' ]\n",
				"  say Dumper( [ \$iter->() ] ); ## ==> [ 'baz' ]\n",
				"\n";
		},
}

	handler
		name      => 'Array:shallow_clone',
		args      => 0,
		template  => '[@{$GET}]',
		documentation => 'Creates a new arrayref with the same elements as the original.',
}

	handler
		name      => 'Array:map',
		args      => 1,
		signature => [CodeRef],
		usage     => '$coderef',
		template  => 'map($ARG->($_), @{$GET})',
		documentation => 'Like C<map> from L<perlfunc>.',
}

	handler
		name      => 'Array:grep',
		args      => 1,
		signature => [CodeRef],
		usage     => '$coderef',
		template  => 'grep($ARG->($_), @{$GET})',
		documentation => 'Like C<grep> from L<perlfunc>.',
}

	handler
		name      => 'Array:sort',
		min_args  => 0,
		max_args  => 1,
		signature => [Optional[CodeRef]],
		usage     => '$coderef?',
		template  => 'my @shv_return = $ARG ? (sort {$ARG->($a,$b)} @{$GET}) : (sort @{$GET})',
		documentation => 'Like C<sort> from L<perlfunc>.',
}

	handler
		name      => 'Array:reverse',
		args      => 0,
		template  => 'reverse @{$GET}',
		documentation => 'Returns the reversed array in list context.',
}

	handler
		name      => 'Array:sort_in_place',
		min_args  => 0,
		max_args  => 1,
		signature => [Optional[CodeRef]],
		usage     => '$coderef?',
		template  => 'my @shv_return = $ARG ? (sort {$ARG->($a,$b)} @{$GET}) : (sort @{$GET}); «\@shv_return»',
		additional_validation => 'no incoming values',
		documentation => 'Like C<sort> from L<perlfunc>, but changes the attribute to point to the newly sorted array.',
}

	require List::Util;
	handler
		name      => 'Array:shuffle',
		args      => 0,
		template  => 'my @shv_return = List::Util::shuffle(@{$GET}); wantarray ? @shv_return : \@shv_return',
		documentation => 'Returns the array in a random order; can be called in list context or scalar context and will return an arrayref in the latter case.',
}

	require List::Util;
	handler
		name      => 'Array:shuffle_in_place',
		args      => 0,
		template  => 'my @shv_return = List::Util::shuffle(@{$GET}); «\@shv_return»',
		additional_validation => 'no incoming values',
		documentation => 'Rearranges the array in a random order, and changes the attribute to point to the new order.',
}

	require List::Util;
	handler
		name      => 'Array:uniq',
		args      => 0,
		template  => 'my @shv_return = List::Util::uniq(@{$GET}); wantarray ? @shv_return : \@shv_return',
		documentation => 'Returns the array filtered to remove duplicates; can be called in list context or scalar context and will return an arrayref in the latter case.',
}

	require List::Util;
	handler
		name      => 'Array:uniq_in_place',
		args      => 0,
		template  => 'my @shv_return = List::Util::uniq(@{$GET}); «\@shv_return»',
		additional_validation => 'no incoming values',
		documentation => 'Filters the array to remove duplicates, and changes the attribute to point to the filtered array.',
}

	require List::Util;
	handler
		name      => 'Array:uniqnum',
		args      => 0,
		template  => 'my @shv_return = List::Util::uniqnum(@{$GET}); wantarray ? @shv_return : \@shv_return',
		documentation => 'Returns the array filtered to remove duplicates numerically; can be called in list context or scalar context and will return an arrayref in the latter case.',
}

	require List::Util;
	handler
		name      => 'Array:uniqnum_in_place',
		args      => 0,
		template  => 'my @shv_return = List::Util::uniqnum(@{$GET}); «\@shv_return»',
		additional_validation => 'no incoming values',
		documentation => 'Filters the array to remove duplicates numerically, and changes the attribute to point to the filtered array.',
}

	require List::Util;
	handler
		name      => 'Array:uniqstr',
		args      => 0,
		template  => 'my @shv_return = List::Util::uniqstr(@{$GET}); wantarray ? @shv_return : \@shv_return',
		documentation => 'Returns the array filtered to remove duplicates stringwise; can be called in list context or scalar context and will return an arrayref in the latter case.',
}

	require List::Util;
	handler
		name      => 'Array:uniqstr_in_place',
		args      => 0,
		template  => 'my @shv_return = List::Util::uniqstr(@{$GET}); «\@shv_return»',
		additional_validation => 'no incoming values',
		documentation => 'Filters the array to remove duplicates stringwise, and changes the attribute to point to the filtered array.',
}

	handler
		name      => 'Array:splice',
		min_args  => 1,
		usage     => '$index, $length, @values',
		template  => 'my @shv_tmp = @{$GET}; my ($shv_index, $shv_length, @shv_values) = @ARG;defined($shv_index) or $shv_index=0; defined($shv_length) or $shv_length=0; my @shv_return = splice(@shv_tmp, $shv_index, $shv_length, @shv_values); «\\@shv_tmp»; wantarray ? @shv_return : $shv_return[-1]',
		lvalue_template => 'my ($shv_index, $shv_length, @shv_values) = @ARG;splice(@{$GET}, $shv_index, $shv_length, @shv_values)',
		additional_validation => sub {
			my $self = CORE::shift;
			my ($sig_was_checked, $gen) = @_;
			my $env = {};
			my $code = sprintf 'if (%s >= 1) { %s }; if (%s >= 2) { %s };',
				$gen->generate_argc,
				$gen->generate_type_assertion( $env, Int, $gen->generate_arg( 1 ) ),
				$gen->generate_argc,
				$gen->generate_type_assertion( $env, Int, $gen->generate_arg( 2 ) );
			my $ti = __PACKAGE__->_type_inspector($gen->isa);
			if ($ti and $ti->{trust_mutated} eq 'always') {
				return { code => $code, env => $env };
			}
			if ($ti and $ti->{trust_mutated} eq 'maybe') {
				my $coercion = ( $gen->coerce and $ti->{value_type}->has_coercion );
				if ( $coercion ) {
					$code .= sprintf(
						'my @shv_unprocessed=%s;my @shv_processed=splice(@shv_unprocessed,0,2); push @shv_processed, map { my $shv_value = $_; %s } @shv_unprocessed;',
						$gen->generate_args,
						$gen->generate_type_assertion( $env, $ti->{value_type}, '$shv_value' ),
					);
				}
				else {
					$code .= sprintf(
						'my @shv_unprocessed=%s;my @shv_processed=splice(@shv_unprocessed,0,2);for my $shv_value (@shv_unprocessed) { %s };push @shv_processed, @shv_unprocessed;',
						$gen->generate_args,
						$gen->generate_type_assertion( $env, $ti->{value_type}, '$shv_value' ),
					);
				}
				return {
					code => $code,
					env  => $env,
					arg  => sub { "\$shv_processed[($_[0])-1]" },
					args => sub { '@shv_processed' },
					argc => sub { 'scalar(@shv_processed)' },
				};
			}
			return { code => $code, env => $env, final_type_check_needed => !!1 };
		},
		documentation => 'Like C<splice> from L<perlfunc>.',
}

	handler
		name      => 'Array:delete',
		args      => 1,
		signature => [Int],
		usage     => '$index',
		template  => 'my @shv_tmp = @{$GET}; my ($shv_return) = splice(@shv_tmp, $ARG, 1); «\\@shv_tmp»; $shv_return',
		lvalue_template => 'splice(@{$GET}, $ARG, 1)',
		additional_validation => 'no incoming values',
		documentation => 'Removes the indexed element from the array and returns it. Elements after it will be "moved up".',
}

	my $me = CORE::shift;
	handler
		name      => 'Array:insert',
		args      => 2,
		signature => [Int, Any],
		usage     => '$index, $value',
		template  => 'my @shv_tmp = @{$GET}; my ($shv_return) = splice(@shv_tmp, $ARG[1], 0, $ARG[2]); «\\@shv_tmp»;',
		lvalue_template => 'splice(@{$GET}, $ARG[1], 0, $ARG[2])',
		additional_validation => $additional_validation_for_set_and_insert,
		documentation => 'Inserts a value into the array with the given index. Elements after it will be "moved down".',
		_examples => sub {
			my ( $class, $attr, $method ) = @_;
			return CORE::join "",
				"  my \$object = $class\->new( $attr => [ 'foo', 'bar', 'baz' ] );\n",
				"  \$object->$method( 1, 'quux' );\n",
				"  say Dumper( \$object->$attr ); ## ==> [ 'foo', 'quux', 'bar', 'baz' ]\n",
				"\n";
		},
}

	my $me = __PACKAGE__;
	handler
		name      => 'Array:flatten_deep',
		min_args  => 0,
		max_args  => 1,
		signature => [Optional[Int]],
		usage     => '$depth?',
		template  => 'my $shv_fd; $shv_fd = sub { my $d=pop; --$d if defined $d; map ref() eq "ARRAY" ? (defined $d && $d < 0) ? $_ : $shv_fd->(@$_, $d) : $_, @_ }; $shv_fd->(@{$GET}, $ARG)',
		documentation => 'Flattens the arrayref into a list, including any nested arrayrefs. (Has the potential to loop infinitely.)',
		_examples => sub {
			my ( $class, $attr, $method ) = @_;
			return CORE::join "",
				"  my \$object = $class\->new( $attr => [ 'foo', [ 'bar', [ 'baz' ] ] ] );\n",
				"  say Dumper( [ \$object->$method ] ); ## ==> [ 'foo', 'bar', 'baz' ]\n",
				"\n",
				"  my \$object2 = $class\->new( $attr => [ 'foo', [ 'bar', [ 'baz' ] ] ] );\n",
				"  say Dumper( [ \$object->$method(1) ] ); ## ==> [ 'foo', 'bar', [ 'baz' ] ]\n",
				"\n";
		},
}

	handler
		name      => 'Array:join',
		min_args  => 0,
		max_args  => 1,
		signature => [Optional[Str]],
		usage     => '$with?',
		template  => 'my $shv_param_with = #ARG ? $ARG : q[,]; join($shv_param_with, @{$GET})',
		documentation => 'Returns a string joining all the elements in the array; if C<< $with >> is omitted, defaults to a comma.',
		_examples => sub {
			my ( $class, $attr, $method ) = @_;
			return CORE::join "",
				"  my \$object = $class\->new( $attr => [ 'foo', 'bar', 'baz' ] );\n",
				"  say \$object->$method;        ## ==> 'foo,bar,baz'\n",
				"  say \$object->$method( '|' ); ## ==> 'foo|bar|baz'\n",
				"\n";
		},
}

	handler
		name      => 'Array:print',
		min_args  => 0,
		max_args  => 2,
		signature => [Optional[FileHandle], Optional[Str]],
		usage     => '$fh?, $with?',
		template  => 'my $shv_param_with = (#ARG>1) ? $ARG[2] : q[,]; print {$ARG[1]||*STDOUT} join($shv_param_with, @{$GET})',
		documentation => 'Prints a string joining all the elements in the array; if C<< $fh >> is omitted, defaults to STDOUT; if C<< $with >> is omitted, defaults to a comma.',
}

	handler
		name      => 'Array:head',
		args      => 1,
		signature => [Int],
		usage     => '$count',
		template  => 'my $shv_count=$ARG; $shv_count=@{$GET} if $shv_count>@{$GET}; $shv_count=@{$GET}+$shv_count if $shv_count<0; (@{$GET})[0..($shv_count-1)]',
		documentation => 'Returns the first C<< $count >> elements of the array in list context.',
}

	handler
		name      => 'Array:tail',
		args      => 1,
		signature => [Int],
		usage     => '$count',
		template  => 'my $shv_count=$ARG; $shv_count=@{$GET} if $shv_count>@{$GET}; $shv_count=@{$GET}+$shv_count if $shv_count<0; my $shv_start = scalar(@{$GET})-$shv_count; my $shv_end = scalar(@{$GET})-1; (@{$GET})[$shv_start..$shv_end]',
		documentation => 'Returns the last C<< $count >> elements of the array in list context.',
}

	handler
		name      => 'Array:apply',
		args      => 1,
		signature => [CodeRef],
		usage     => '$coderef',
		template  => 'my @shv_tmp = @{$GET}; &{$ARG} foreach @shv_tmp; wantarray ? @shv_tmp : $shv_tmp[-1]',
		documentation => 'Executes the coderef (which should modify C<< $_ >>) against each element of the array; returns the resulting array in list context.',
}

	require List::Util;
	handler
		name      => 'Array:pick_random',
		min_args  => 0,
		max_args  => 1,
		signature => [Optional[Int]],
		usage     => '$count',
		template  => 'my @shv_tmp = List::Util::shuffle(@{$GET}); my $shv_count = $ARG; $shv_count=@{$GET} if $shv_count > @{$GET}; $shv_count=@{$GET}+$shv_count if $shv_count<0; if (wantarray and #ARG) { @shv_tmp[0..$shv_count-1] } elsif (#ARG) { [@shv_tmp[0..$shv_count-1]] } else { $shv_tmp[0] }',
		documentation => 'If no C<< $count >> is given, returns one element of the array at random. If C<< $count >> is given, creates a new array with that many random elements from the original array (or fewer if the original array is not long enough) and returns that as an arrayref or list depending on context',
}

	handler
		name      => 'Array:for_each',
		args      => 1,
		signature => [CodeRef],
		usage     => '$coderef',
		template  => 'foreach my $shv_index (0 .. $#{$GET}) { &{$ARG}(($GET)->[$shv_index], $shv_index) }; $SELF',
		documentation => 'Chainable method which executes the coderef on each element of the array. The coderef will be passed two values: the element and its index.',
		_examples => sub {
			my ( $class, $attr, $method ) = @_;
			return CORE::join "",
				"  my \$object = $class\->new( $attr => [ 'foo', 'bar', 'baz' ] );\n",
				"  \$object->$method( sub { say \"Item \$_[1] is \$_[0].\" } );\n",
				"\n";
		},
}

	handler
		name      => 'Array:for_each_pair',
		args      => 1,
		signature => [CodeRef],
		usage     => '$coderef',
		template  => 'for (my $shv_index=0; $shv_index<@{$GET}; $shv_index+=2) { &{$ARG}(($GET)->[$shv_index], ($GET)->[$shv_index+1]) }; $SELF',
		documentation => 'Chainable method which executes the coderef on each pair of elements in the array. The coderef will be passed the two elements.',
}

	require List::Util;
	handler
		name      => 'Array:all_true',
		args      => 1,
		signature => [CodeRef],
		usage     => '$coderef',
		template  => '&List::Util::all($ARG, @{$GET})',
		documentation => 'Like C<< List::Util::all() >>.',
}

	require List::Util;
	handler
		name      => 'Array:not_all_true',
		args      => 1,
		signature => [CodeRef],
		usage     => '$coderef',
		template  => '&List::Util::notall($ARG, @{$GET})',
		documentation => 'Like C<< List::Util::notall() >>.',
}

	require List::Util;
	handler
		name      => 'Array:min',
		args      => 0,
		template  => '&List::Util::min(@{$GET})',
		documentation => 'Like C<< List::Util::min() >>.',
}

	require List::Util;
	handler
		name      => 'Array:max',
		args      => 0,
		template  => '&List::Util::max(@{$GET})',
		documentation => 'Like C<< List::Util::max() >>.',
}

	require List::Util;
	handler
		name      => 'Array:minstr',
		args      => 0,
		template  => '&List::Util::minstr(@{$GET})',
		documentation => 'Like C<< List::Util::minstr() >>.',
}

	require List::Util;
	handler
		name      => 'Array:maxstr',
		args      => 0,
		template  => '&List::Util::maxstr(@{$GET})',
		documentation => 'Like C<< List::Util::maxstr() >>.',
}

	require List::Util;
	handler
		name      => 'Array:sum',
		args      => 0,
		template  => '&List::Util::sum(0, @{$GET})',
		documentation => 'Like C<< List::Util::sum0() >>.',
}

	require List::Util;
	handler
		name      => 'Array:product',
		args      => 0,
		template  => '&List::Util::product(1, @{$GET})',
		documentation => 'Like C<< List::Util::product() >>.',
}

	require List::Util;
	handler
		name      => 'Array:sample',
		args      => 1,
		signature => [Int],
		usage     => '$count',
		template  => '&List::Util::sample($ARG, @{$GET})',
		documentation => 'Like C<< List::Util::sample() >>.',
}

	require List::Util;
	handler
		name      => 'Array:reductions',
		args      => 1,
		signature => [CodeRef],
		usage     => '$coderef',
		template  => 'my $shv_callback = $ARG; List::Util::reductions { $shv_callback->($a,$b) } @{$GET}',
		documentation => 'Like C<< List::Util::reductions() >>.',
}

	require List::Util;
	handler
		name      => 'Array:pairs',
		args      => 0,
		template  => '&List::Util::pairs(@{$GET})',
		documentation => 'Like C<< List::Util::pairs() >>.',
}

	require List::Util;
	handler
		name      => 'Array:pairkeys',
		args      => 0,
		template  => '&List::Util::pairkeys(@{$GET})',
		documentation => 'Like C<< List::Util::pairkeys() >>.',
}

	require List::Util;
	handler
		name      => 'Array:pairvalues',
		args      => 0,
		template  => '&List::Util::pairvalues(@{$GET})',
		documentation => 'Like C<< List::Util::pairvalues() >>.',
}

	require List::Util;
	handler
		name      => 'Array:pairgrep',
		args      => 1,
		signature => [CodeRef],
		usage     => '$coderef',
		template  => 'List::Util::pairgrep { $ARG->($_) } @{$GET}',
		documentation => 'Like C<< List::Util::pairgrep() >>.',
}

	require List::Util;
	handler
		name      => 'Array:pairfirst',
		args      => 1,
		signature => [CodeRef],
		usage     => '$coderef',
		template  => 'List::Util::pairfirst { $ARG->($_) } @{$GET}',
		documentation => 'Like C<< List::Util::pairfirst() >>.',
}

	require List::Util;
	handler
		name      => 'Array:pairmap',
		args      => 1,
		signature => [CodeRef],
		usage     => '$coderef',
		template  => 'List::Util::pairmap { $ARG->($_) } @{$GET}',
		documentation => 'Like C<< List::Util::pairmap() >>.',
}

	handler
		name      => 'Array:reset',
		args      => 0,
		template  => '« $DEFAULT »',
		default_for_reset => sub { '[]' },
		documentation => 'Resets the attribute to its default value, or an empty arrayref if it has no default.',
		_examples => sub {
			my ( $class, $attr, $method ) = @_;
			return CORE::join "",
				"  my \$object = $class\->new( $attr => [ 'foo', 'bar', 'baz' ] );\n",
				"  \$object->$method;\n",
				"  say Dumper( \$object->$attr ); ## ==> []\n",
				"\n";
		},
}

1;