NAME
Venus::Map - Map Class
ABSTRACT
Map Class for Perl 5
SYNOPSIS
package main;
use Venus::Map;
my $map = Venus::Map->new({1..8});
# $map->count;
# 4
DESCRIPTION
This package provides a representation of a collection of ordered key/value pairs and methods for validating and manipulating it.
ATTRIBUTES
This package has the following attributes:
accept
accept(string $data) (string)
The accept attribute is read-write, accepts (string) values, and is optional.
Since 4.11
- accept example 1
-
# given: synopsis package main; my $map_accept = $map->accept("number"); # "number"
- accept example 2
-
# given: synopsis # given: example-1 accept package main; my $get_accept = $map->accept; # "number"
INHERITS
This package inherits behaviors from:
INTEGRATES
This package integrates behaviors from:
METHODS
This package provides the following methods:
all
all(coderef $code) (boolean)
The all method returns true if the callback returns true for all of the elements.
Since 4.11
- all example 2
-
# given: synopsis; my $all = $map->all(sub { my ($key, $value) = @_; $value > 0; }); # 1
any
any(coderef $code) (boolean)
The any method returns true if the callback returns true for any of the elements.
Since 4.11
attest
attest() (any)
The attest method validates the values using the Venus::Assert expression in the "accept" attribute and returns the result.
Since 4.11
- attest example 2
-
# given: synopsis package main; $map->accept('number | object'); my $attest = $map->attest; # {1..8}
- attest example 3
-
# given: synopsis package main; $map->accept('string'); my $attest = $map->attest; # Exception! (isa Venus::Check::Error)
- attest example 4
-
# given: synopsis package main; $map->accept('number'); my $attest = $map->attest; # {1..8}
call
call(string $iterable, string $method) (any)
The call method executes the given method (named using the first argument) which performs an iteration (i.e. takes a callback) and calls the method (named using the second argument) on the object (or value) and returns the result of the iterable method.
Since 4.11
- call example 1
-
package main; my $map = Venus::Map->new; $map->set(1..8); my $call = $map->call('map', 'incr'); # [3,5,7,9]
- call example 2
-
package main; my $map = Venus::Map->new; $map->set(1..8); my $call = $map->call('grep', 'gt', 4); # [6,8]
contains
contains(any $value) (boolean)
The contains method returns true if the value provided already exists in the map, otherwise it returns false.
Since 4.11
count
count() (number)
The count method returns the number of elements within the map.
Since 4.11
default
default() (hashref)
The default method returns the default value, i.e. {}.
Since 4.11
delete
delete(string $key) (any)
The delete method returns the value of the element corresponding to the key specified after removing it from the map.
Since 4.11
difference
difference(hashref | Venus::Hash | Venus::Map $data) (Venus::Map)
The difference method returns a new map containing only the values that don't exist in the source.
Since 4.11
- difference example 1
-
# given: synopsis package main; my $difference = $map->difference({7..10}); # bless(..., "Venus::Map") # $difference->list; # [10]
- difference example 2
-
# given: synopsis package main; my $difference = $map->difference(Venus::Map->new({7,8,9,10,11,12})); # bless(..., "Venus::Map") # $difference->list; # [10, 12]
- difference example 3
-
# given: synopsis package main; use Venus::Hash; my $difference = $map->difference(Venus::Hash->new({7,8,9,10,11,12})); # bless(..., "Venus::Map") # $difference->list; # [10, 12]
different
different(hashref | Venus::Hash | Venus::Map $data) (boolean)
The different method returns true if the values provided don't exist in the source.
Since 4.11
- different example 1
-
# given: synopsis package main; my $different = $map->different({1..10}); # true
- different example 2
-
# given: synopsis package main; my $different = $map->different({1..8}); # false
each
each(coderef $code) (hashref)
The each method executes a callback for each element in the map passing the key and value as arguments. This method can return a list of values in list-context.
Since 4.11
- each example 1
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $each = $map->each(sub { [$_] }); # [[2], [4], [6], [8]]
- each example 2
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(8,7,6,5,4,3,2,1); my $each = $map->each(sub { my ($key, $value) = @_; [$key, $value] }); # [ # [8, 7], # [6, 5], # [4, 3], # [2, 1], # ]
empty
empty() (Venus::Hash)
The empty method drops all elements from the map.
Since 4.11
exists
exists(string $key) (boolean)
The exists method returns true if the element corresponding with the key specified exists, otherwise it returns false.
Since 4.11
first
first() (any)
The first method returns the value of the first element.
Since 4.11
- first example 1
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $first = $map->first; # 2
- first example 2
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(8,7,6,5,4,3,2,1); my $first = $map->first; # 7
get
get(string $key) (any)
The get method returns the value at the position specified.
Since 4.11
grep
grep(coderef $code) (hashref)
The grep method executes a callback for each element in the array passing the value as an argument, returning a new array reference containing the elements for which the returned true. This method can return a list of values in list-context.
Since 4.11
- grep example 1
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $grep = $map->grep(sub { $_ > 4 }); # [6,8]
- grep example 2
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $grep = $map->grep(sub { my ($key, $value) = @_; $value > 4 }); # [6,8]
head
head(number $size) (hashref)
The head method returns the topmost elements, limited by the desired size specified.
Since 4.11
- head example 1
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $head = $map->head; # [2]
- head example 2
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $head = $map->head(1); # [2]
- head example 3
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $head = $map->head(2); # [2,4]
- head example 4
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $head = $map->head(5); # [2,4,6,8]
- head example 5
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $head = $map->head(20); # [2,4,6,8]
intersect
intersect(hashref | Venus::Hash | Venus::Map $data) (boolean)
The intersect method returns true if the values provided already exist in the source.
Since 4.11
- intersect example 2
-
# given: synopsis package main; my $intersect = $map->intersect({9,10}); # false
intersection
intersection(hashref | Venus::Hash | Venus::Map $data) (Venus::Map)
The intersection method returns a new map containing only the values that already exist in the source.
Since 4.11
- intersection example 1
-
# given: synopsis package main; $map->push(9,10); my $intersection = $map->intersection({9,10,11,12}); # bless(..., "Venus::Map") # $intersection->list; # [10]
- intersection example 2
-
# given: synopsis package main; $map->push(9,10); my $intersection = $map->intersection(Venus::Map->new({9,10,11,12})); # bless(..., "Venus::Map") # $intersection->list; # [10]
- intersection example 3
-
# given: synopsis package main; use Venus::Hash; $map->push(9,10); my $intersection = $map->intersection(Venus::Hash->new({9,10,11,12})); # bless(..., "Venus::Map") # $intersection->list; # [10]
iterator
iterator() (coderef)
The iterator method returns a code reference which can be used to iterate over the array. Each time the iterator is executed it will return the next element in the array until all elements have been seen, at which point the iterator will return an undefined value. This method can return a tuple with the key and value in list-context.
Since 4.11
- iterator example 1
-
# given: synopsis; my $iterator = $map->iterator; # sub { ... } # while (my $value = $iterator->()) { # say $value; # 1 # }
- iterator example 2
-
# given: synopsis; my $iterator = $map->iterator; # sub { ... } # while (grep defined, my ($key, $value) = $iterator->()) { # say $value; # 1 # }
join
join(string $seperator) (string)
The join method returns a string consisting of all the elements in the array joined by the join-string specified by the argument. Note: If the argument is omitted, an empty string will be used as the join-string.
Since 4.11
- join example 1
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $join = $map->join; # 2468
- join example 2
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $join = $map->join(', '); # "2, 4, 6, 8"
keys
keys() (hashref)
The keys method returns an array reference consisting of the indicies of the array.
Since 4.11
- keys example 1
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $keys = $map->keys; # [1,3,5,7]
last
last() (any)
The last method returns the value of the last element in the array.
Since 4.11
- last example 1
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $last = $map->last; # 8
length
length() (number)
The length method returns the number of elements within the array, and is an alias for the "count" method.
Since 4.11
list
list() (any)
The list method returns a shallow copy of the underlying array reference as an array reference.
Since 4.11
- list example 1
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $list = $map->list; # 4
- list example 2
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my @list = $map->list; # (2,4,6,8)
map
map(coderef $code) (hashref)
The map method iterates over each element in the array, executing the code reference supplied in the argument, passing the routine the value at the current position in the loop and returning a new array reference containing the elements for which the argument returns a value or non-empty list. This method can return a list of values in list-context.
Since 4.11
- map example 1
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $result = $map->map(sub { $_ * 2 }); # [4,8,12,16]
- map example 2
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $result = $map->map(sub { my ($key, $value) = @_; [$key, ($value * 2)] }); # [ # [1, 4], # [3, 8], # [5, 12], # [7, 16], # ]
merge
merge(any @data) (Venus::Map)
The merge method merges the arguments provided with the existing map.
Since 4.11
- merge example 1
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $merge = $map->merge(7..10); # bless(..., "Venus::Map") # $map->list; # [2,4,6,8,10]
- merge example 2
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $merge = $map->merge(Venus::Map->new->do('set', 5..10)); # bless(..., "Venus::Map") # $map->list; # [2,4,6,8,10]
new
new(any @args) (Venus::Map)
The new method constructs an instance of the package.
Since 4.15
- new example 2
-
package main; use Venus::Map; my $new = Venus::Map->new({1..8}); # bless(..., "Venus::Map")
- new example 3
-
package main; use Venus::Map; my $new = Venus::Map->new(value => {1..8}); # bless(..., "Venus::Map")
none
none(coderef $code) (boolean)
The none method returns true if none of the elements in the array meet the criteria set by the operand and rvalue.
Since 4.11
- none example 2
-
# given: synopsis; my $none = $map->none(sub { my ($key, $value) = @_; $value < 1 }); # 1
one
one(coderef $code) (boolean)
The one method returns true if only one of the elements in the array meet the criteria set by the operand and rvalue.
Since 4.11
- one example 2
-
# given: synopsis; my $one = $map->one(sub { my ($key, $value) = @_; $value == 2 }); # 1
order
order(number @indices) (Venus::Map)
The order method reorders the array items based on the indices provided and returns the invocant.
Since 4.11
- order example 1
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $order = $map->order; # bless(..., "Venus::Map") # $map->keys; # [1,3,5,7]
- order example 2
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $order = $map->order(5,3); # bless(..., "Venus::Map") # $map->keys; # [5,3,1,7]
- order example 3
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $order = $map->order(7); # bless(..., "Venus::Map") # $map->keys; # [7,1,3,5]
pairs
pairs() (hashref)
The pairs method is an alias to the pairs_array method. This method can return a list of values in list-context.
Since 4.11
- pairs example 1
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $pairs = $map->pairs; # [ # [1, 2], # [3, 4], # [5, 6], # [7, 8], # ]
part
part(coderef $code) (tuple[hashref, hashref])
The part method iterates over each element in the array, executing the code reference supplied in the argument, using the result of the code reference to partition to array into two distinct array references. This method can return a list of values in list-context.
Since 4.11
- part example 1
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $part = $map->part(sub { $_ > 4 }); # [{5..8}, {1..4}]
- part example 2
-
# given: synopsis; my $part = $map->part(sub { my ($key, $value) = @_; $value < 5 }); # [{1..4}, {5..8}]
pop
pop() (any)
The pop method returns the last element of the array shortening it by one. Note, this method modifies the array.
Since 4.11
- pop example 1
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $pop = $map->pop; # 8
push
push(any @data) (hashref)
The push method appends the array by pushing the agruments onto it and returns itself.
Since 4.11
- push example 1
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $push = $map->push(9,10); # {1..10}
random
random() (any)
The random method returns a random element from the array.
Since 4.11
- random example 1
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $random = $map->random; # 2 # my $random = $map->random; # 1
range
range(number | string @args) (hashref)
The range method accepts a "range expression" and returns the result of calling the "slice" method with the computed range.
Since 4.11
- range example 2
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); package main; my $range = $map->range(0); # [2]
- range example 3
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); package main; my $range = $map->range('0:'); # [2,4,6,8]
- range example 4
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); package main; my $range = $map->range(':2'); # [2,4,6]
- range example 5
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); package main; my $range = $map->range('3:'); # [8]
- range example 7
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); package main; my $range = $map->range('0:1'); # [2,4]
- range example 8
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); package main; my $range = $map->range('2:4'); # [6,8]
- range example 9
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); package main; my $range = $map->range(0..2); # [2,4,6]
- range example 10
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); package main; my $range = $map->range('-1:3'); # [8]
- range example 11
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); package main; my $range = $map->range('0:4'); # [2,4,6,8]
- range example 12
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); package main; my $range = $map->range('0:-2'); # [2,4,6]
- range example 13
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); package main; my $range = $map->range('-2:-2'); # [6]
- range example 19
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); package main; my $range = $map->range('-4:-1'); # [2,4,6,8]
reverse
reverse() (arrayref)
The reverse method returns an array reference containing the elements in the array in reverse order.
Since 4.11
- reverse example 1
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $reverse = $map->reverse; # [8,6,4,2]
rotate
rotate() (arrayref)
The rotate method rotates the elements in the array such that first elements becomes the last element and the second element becomes the first element each time this method is called.
Since 4.11
- rotate example 1
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $rotate = $map->rotate; # [4,6,8,2]
rsort
rsort() (arrayref)
The rsort method returns an array reference containing the values in the array sorted alphanumerically in reverse.
Since 4.11
set
set(any %pairs) (hashref)
The set method inserts a new value into the map if it doesn't exist.
Since 4.11
- set example 1
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); package main; $map = $map->set(9,10); # {1..10}
- set example 2
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); package main; $map = $map->set(1..8); # {1..8}
shift
shift() (any)
The shift method returns the first element of the array shortening it by one.
Since 4.11
- shift example 1
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $shift = $map->shift; # 2
shuffle
shuffle() (arrayref)
The shuffle method returns an array with the values returned in a randomized order.
Since 4.11
- shuffle example 1
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..20); my $shuffle = $map->shuffle; # [6, 12, 2, 20, 18, 16, 10, 4, 8, 14]
slice
slice(string @keys) (hashref)
The slice method returns a hash reference containing the elements in the array at the positions specified in the arguments.
Since 4.11
- slice example 1
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $slice = $map->slice(0, 1); # [2, 4]
- slice example 2
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $slice = $map->slice(3, 1); # [8, 4]
sort
sort() (hashref)
The sort method returns an array reference containing the values in the array sorted alphanumerically.
Since 4.11
- sort example 1
-
package main; use Venus::Map; my $map = Venus::Map->new({1 => 'a', 2 => 'b', 3 => 'c', 4 => 'd'}); my $sort = $map->sort; # ["a".."d"]
subset
subset(hashref | Venus::Hash | Venus::Map $data) (boolean)
The subset method returns true if all the values provided already exist in the source.
Since 4.11
superset
superset(hashref | Venus::Hash | Venus::Map $data) (boolean)
The superset method returns true if all the values in the source exists in the values provided.
Since 4.11
tail
tail(number $size) (hashref)
The tail method returns the bottommost elements, limited by the desired size specified.
Since 4.11
- tail example 1
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $tail = $map->tail; # [8]
- tail example 2
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $tail = $map->tail(1); # [8]
- tail example 3
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $tail = $map->tail(2); # [6,8]
- tail example 4
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $tail = $map->tail(4); # [2,4,6,8]
- tail example 5
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $tail = $map->tail(20); # [2,4,6,8]
unshift
unshift(any @data) (hashref)
The unshift method prepends the array by pushing the agruments onto it and returns itself.
Since 4.11
- unshift example 1
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->set(1..8); my $unshift = $map->unshift(9,10,11,12); # {1..12}
- unshift example 2
-
package main; use Venus::Map; my $map = Venus::Map->new; $map->do('set', 1..8); # my $unshift = $map->unshift(9,10,11,12); # {1..12} # $map->keys; # [9,11,1,3,5,7]
values
values() (arrayref)
The values method returns an array reference consisting of all the values in the hash.
Since 4.15
AUTHORS
Awncorp, awncorp@cpan.org
LICENSE
Copyright (C) 2022, Awncorp, awncorp@cpan.org.
This program is free software, you can redistribute it and/or modify it under the terms of the Apache license version 2.0.