/ 
List-Utils-MoveElement-0.01
River stage one • 1 direct dependent • 2 total dependents
/ List::Utils::MoveElement

NAME

List::Utils::MoveElement - Move elements of a list, optionally with XS.

SYNOPSIS

use List::Utils::MoveElement;

my @fruit = qw/apple banana cherry date eggplant/;

my @array = move_element_to_beginning(2, @fruit);
# returns (cherry apple banana date eggplant)

@array = move_element_to_end(0, @fruit);
# returns (banana cherry date eggplant apple)

@array = move_element_left(-1, @array);
# returns (apple banana cherry eggplant date)

@array = move_element_right(0, @array);
# returns (banana apple cherry date eggplant)

INSTALL

The XS module is built by default. To enable the pure Perl version only, pass --pureperl-only to Build.PL or, if installing via cpanm, --pp (or --pureperl).

DESCRIPTION

List::Utils::Move provides four functions for moving an element of an array to the beginning or end of the array, or left or right by one place. All functions return the new array without modifying the original.

move_element_left

@array = move_element_left(N, @array)

Moves element N of @array left by one place by swapping element N with element N-1.

If N is already the first element, it does nothing.

move_right

@array = move_element_right(N, @array)

Moves element N of @array right by one place by swapping element N with element N+1.

If N is already the last element, it does nothing.

to_beginning

@array = move_element_to_beginning(N, @array)

Moves element N of @array to the beginning of the array, shifting elements to the right as necessary. In other words, element N becomes element 0 and elements 0..N-1 become elements 1..N.

If N is already the first element, it does nothing.

to_end

@array = move_element_to_end(N, @array)

Moves element N of @array to the end of the array, shifting elements to the left as necessary. In other words, element N becomes element $#array and elements N..$#array become elements N+1..$#array.

If N is already the last element, it does nothing.

EXPORT

By default all four functions are exported. If you would rather not import anything, you can use the shorter function names (without the "move_element_" prefix) in the following style:

use List::Utils::MoveElement (); # Do not import
@array = List::Utils::MoveElement::left(1, @array);

BUGS and CAVEATS

There is a difference between the Pure Perl and XS versions of this module when one if its functions is called in scalar context.

The Pure Perl functions will return the number of elements in the list, while the XS version will return the last element.

Scalar context of these functions does not seem useful, so I do not plan to address this inconsistency.

SEE ALSO

List::Util, List::MoreUtils

AUTHOR

Dondi Michael Stroma, <dstroma@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2017, 2021 by Dondi Michael Stroma

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.