# 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](https://metacpan.org/pod/List%3A%3AUtil), [List::MoreUtils](https://metacpan.org/pod/List%3A%3AMoreUtils) # AUTHOR Dondi Michael Stroma, # 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.