NAME

Venus::Range - Range Class

ABSTRACT

Range Class for Perl 5

SYNOPSIS

package main;

use Venus::Range;

my $range = Venus::Range->new(['a'..'i']);

# $array->parse('0:2');

# ['a', 'b', 'c']

DESCRIPTION

This package provides methods for selecting elements from an arrayref using range expressions. A "range expression" is a string that specifies a subset of elements in an array or arrayref, defined by a start, stop, and an optional step value, separated by colons. For example, the expression '1:4' will select elements starting from index 1 to index 4 (both inclusive). The components of the range expression are:

Start: The beginning index of the selection. If this value is negative, it counts from the end of the array, where -1 is the last element.
Stop: The ending index of the selection. This value is also inclusive, meaning the element at this index will be included in the selection. Negative values count from the end of the array.
Step: An optional value that specifies the interval between selected elements. For instance, a step of 2 will select every second element. If not provided, the default step is 1.

This package uses inclusive start and stop indices, meaning both bounds are included in the selection. This differs from some common conventions where the stop value is exclusive. The package also gracefully handles out-of-bound indices. If the start or stop values exceed the length of the array, they are adjusted to fit within the valid range without causing errors. Negative indices are also supported, allowing for easy reverse indexing from the end of the array.

ATTRIBUTES

This package has the following attributes:

start

start(number $start) (number)

The start attribute is read-write, accepts (number) values, and is optional.

Since 4.15

start example 1

# given: synopsis

package main;

my $start = $range->start(0);

# 0

start example 2

# given: synopsis

# given: example-1 start

package main;

$start = $range->start;

# 0

stop

stop(number $stop) (number)

The stop attribute is read-write, accepts (number) values, and is optional.

Since 4.15

stop example 1

# given: synopsis

package main;

my $stop = $range->stop(9);

# 9

stop example 2

# given: synopsis

# given: example-1 stop

package main;

$stop = $range->stop;

# 9

step

step(number $step) (number)

The step attribute is read-write, accepts (number) values, and is optional.

Since 4.15

step example 1

# given: synopsis

package main;

my $step = $range->step(1);

# 1

step example 2

# given: synopsis

# given: example-1 step

package main;

$step = $range->step;

# 1

INHERITS

This package inherits behaviors from:

Venus::Kind::Utility

INTEGRATES

This package integrates behaviors from:

Venus::Role::Valuable

METHODS

This package provides the following methods:

after

after(number $index) (arrayref)

The after method selects the elements after the index provided and returns the selection using "select". The selection is not inclusive.

Since 4.15

after example 1

# given: synopsis

package main;

my $after = $range->after;

# []

after example 2

# given: synopsis

package main;

my $after = $range->after(5);

# ['g', 'h', 'i']

before

before(number $index) (arrayref)

The before method selects the elements before the index provided and returns the selection using "select". The selection is not inclusive.

Since 4.15

before example 1

# given: synopsis

package main;

my $before = $range->before;

# []

before example 2

# given: synopsis

package main;

my $before = $range->before(5);

# ['a'..'e']

iterate

iterate( ) (coderef)

The iterate method returns an iterator which uses "select" to iteratively return each element of the selection.

Since 4.15

iterate example 1

# given: synopsis

package main;

my $iterate = $range->iterate;

# sub{...}

iterate example 2

package main;

my $range = Venus::Range->parse('4:', ['a'..'i']);

my $iterate = $range->iterate;

# sub{...}

new

new(any @args) (Venus::Range)

The new method constructs an instance of the package.

Since 4.15

new example 1

package main;

use Venus::Range;

my $range = Venus::Range->new;

# bless(..., 'Venus::Range')

new example 2

package main;

use Venus::Range;

my $range = Venus::Range->new(['a'..'d']);

# bless(..., 'Venus::Range')

new example 3

package main;

use Venus::Range;

my $range = Venus::Range->new(value => ['a'..'d']);

# bless(..., 'Venus::Range')

parse

parse(string $expr, arrayref $data) (Venus::Range)

The parse method parses the "range expression" provided and returns a new instance of Venus::Range representing the range expression, optionally accepting and setting the arrayref to be used as the selection source. This method can also be used as a class method.

Since 4.15

parse example 1

# given: synopsis

package main;

my $parse = $range->parse('4:');

# bless(..., "Venus::Range")

# $parse->start
# 4

# $parse->stop
# -1

# $parse->step
# 1

parse example 2

# given: synopsis

package main;

my $parse = $range->parse('0:1');

# bless(..., "Venus::Range")

# $parse->start
# 0

# $parse->stop
# 1

# $parse->step
# 1

parse example 3

# given: synopsis

package main;

my $parse = $range->parse('1:0');

# bless(..., "Venus::Range")

# $parse->start
# 1

# $parse->stop
# 0

# $parse->step
# 1

parse example 4

# given: synopsis

package main;

my $parse = $range->parse('2::2');

# bless(..., "Venus::Range")

# $parse->start
# 2

# $parse->stop
# -1

# $parse->step
# 2

parse example 5

# given: synopsis

package main;

my $parse = $range->parse(':4');

# bless(..., "Venus::Range")

# $parse->start
# 0

# $parse->stop
# 4

# $parse->step
# 1

parse example 6

# given: synopsis

package main;

my $parse = $range->parse(':4:1');

# bless(..., "Venus::Range")

# $parse->start
# 0

# $parse->stop
# 4

# $parse->step
# 1

parse example 7

# given: synopsis

package main;

my $parse = $range->parse(':-2', ['a'..'i']);

# bless(..., "Venus::Range")

# $parse->start
# 0

# $parse->stop
# -2

# $parse->step
# 1

partition

partition(number $index) (tuple[arrayref, arrayref])

The partition method splits the elements into two sets of elements at the index specific and returns a tuple of two arrayrefs. The first arrayref will include everything "before" the index provided, and the second tuple will include everything at and "after" the index provided.

Since 4.15

partition example 1

# given: synopsis

package main;

my $partition = $range->partition;

# [[], ['a'..'i']]

partition example 2

# given: synopsis

package main;

my $partition = $range->partition(0);

# [[], ['a'..'i']]

partition example 3

# given: synopsis

package main;

my $partition = $range->partition(5);

# [['a'..'e'], ['f'..'i']]

select

select() (arrayref)

The select method uses the start, stop, and step attributes to select elements from the arrayref and returns the selection. Returns a list in list context.

Since 4.15

select example 1

package main;

use Venus::Range;

my $range = Venus::Range->parse('4:', ['a'..'i']);

my $select = $range->select;

# ['e'..'i']

select example 2

package main;

use Venus::Range;

my $range = Venus::Range->parse('0:1', ['a'..'i']);

my $select = $range->select;

# ['a', 'b']

select example 3

package main;

use Venus::Range;

my $range = Venus::Range->parse('0:', ['a'..'i']);

my $select = $range->select;

# ['a'..'i']

select example 4

package main;

use Venus::Range;

my $range = Venus::Range->parse(':-2', ['a'..'i']);

my $select = $range->select;

# ['a'..'h']

select example 5

package main;

use Venus::Range;

my $range = Venus::Range->parse('2:8:2', ['a'..'i']);

my $select = $range->select;

# ['c', 'e', 'g', 'i']

split

split(number $index) (tuple[arrayref, arrayref])

The split method splits the elements into two sets of elements at the index specific and returns a tuple of two arrayrefs. The first arrayref will include everything "before" the index provided, and the second tuple will include everything "after" the index provided. This operation will always exclude the element at the index the elements are split on. See "partition" for an inclusive split operation.

Since 4.15

split example 1

# given: synopsis

package main;

my $split = $range->split;

# [[], ['b'..'i']]

split example 2

# given: synopsis

package main;

my $split = $range->split(0);

# [[], ['a'..'i']]

split example 3

# given: synopsis

package main;

my $split = $range->split(5);

# [['a'..'e'], ['g'..'i']]

AUTHORS

Awncorp, awncorp@cpan.org

LICENSE

This program is free software, you can redistribute it and/or modify it under the terms of the Apache license version 2.0.

To install Venus, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Venus

CPAN shell

perl -MCPAN -e shell
install Venus

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

ABSTRACT

SYNOPSIS

DESCRIPTION

ATTRIBUTES

start

stop

step

INHERITS

INTEGRATES

METHODS

after

before

iterate

new

parse

partition

select

split

AUTHORS

LICENSE

Module Install Instructions