NAME

Venus::Set - Set Class

ABSTRACT

Set Class for Perl 5

SYNOPSIS

  package main;
  use Venus::Set;
  my $set = Venus::Set->new([1,1,2,2,3,3,4,4,5..9]);
  # $set->count;
  # 4

DESCRIPTION

This package provides a representation of a collection of ordered unique values 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 $set_accept = $set->accept("number");
  # "number"

accept example 2

  # given: synopsis
  # given: example-1 accept
  package main;
  my $get_accept = $set->accept;
  # "number"

INHERITS

This package inherits behaviors from:

Venus::Kind::Utility

INTEGRATES

This package integrates behaviors from:

Venus::Role::Mappable

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 1

  # given: synopsis;
  my $all = $set->all(sub {
    $_ > 0;
  });
  # 1

all example 2

  # given: synopsis;
  my $all = $set->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

any example 1

  # given: synopsis;
  my $any = $set->any(sub {
    $_ > 4;
  });

any example 2

  # given: synopsis;
  my $any = $set->any(sub {
    my ($key, $value) = @_;
    $value > 4;
  });

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 1

  # given: synopsis
  package main;
  my $attest = $set->attest;
  # [1..9]

attest example 2

  # given: synopsis
  package main;
  $set->accept('number | object');
  my $attest = $set->attest;
  # [1..9]

attest example 3

  # given: synopsis
  package main;
  $set->accept('string');
  my $attest = $set->attest;
  # Exception! (isa Venus::Check::Error)

attest example 4

  # given: synopsis
  package main;
  $set->accept('Venus::Number');
  my $attest = $set->attest;
  # [1..9]

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

  # given: synopsis
  package main;
  my $call = $set->call('map', 'incr');
  # [2..10]

call example 2

  # given: synopsis
  package main;
  my $call = $set->call('grep', 'gt', 4);
  # [4..9]

contains

  contains(any $value) (boolean)

The contains method returns true if the value provided already exists in the set, otherwise it returns false.

Since 4.11

contains example 1

  # given: synopsis;
  my $contains = $set->contains(1);
  # true

contains example 2

  # given: synopsis;
  my $contains = $set->contains(0);
  # false

count

  count() (number)

The count method returns the number of elements within the set.

Since 4.11

count example 1

  # given: synopsis;
  my $count = $set->count;
  # 9

default

  default() (arrayref)

The default method returns the default value, i.e. "[]".

Since 4.11

default example 1

  # given: synopsis;
  my $default = $set->default;
  # []

delete

  delete(number $index) (any)

The delete method returns the value of the element at the index specified after removing it from the array.

Since 4.11

delete example 1

  # given: synopsis;
  my $delete = $set->delete(2);
  # 3

difference

  difference(arrayref | Venus::Array | Venus::Set $data) (Venus::Set)

The difference method returns a new set containing only the values that don't exist in the source.

Since 4.11

difference example 1

  # given: synopsis
  package main;
  my $difference = $set->difference([9, 10, 11]);
  # bless(..., "Venus::Set")
  # $difference->list;
  # [10, 11]

difference example 2

  # given: synopsis
  package main;
  my $difference = $set->difference(Venus::Set->new([9, 10, 11]));
  # bless(..., "Venus::Set")
  # $difference->list;
  # [10, 11]

difference example 3

  # given: synopsis
  package main;
  use Venus::Array;
  my $difference = $set->difference(Venus::Array->new([9, 10, 11]));
  # bless(..., "Venus::Set")
  # $difference->list;
  # [10, 11]

different

  different(arrayref | Venus::Array | Venus::Set $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 = $set->different([1..10]);
  # true

different example 2

  # given: synopsis
  package main;
  my $different = $set->different([1..9]);
  # false

each

  each(coderef $code) (arrayref)

The each method executes a callback for each element in the array passing the index and value as arguments. This method can return a list of values in list-context.

Since 4.11

each example 1

  # given: synopsis;
  my $each = $set->each(sub {
    [$_]
  });
  # [[1], [2], [3], [4], [5], [6], [7], [8], [9]]

each example 2

  # given: synopsis;
  my $each = $set->each(sub {
    my ($key, $value) = @_;
    [$key, $value]
  });
  # [
  #   [0, 1],
  #   [1, 2],
  #   [2, 3],
  #   [3, 4],
  #   [4, 5],
  #   [5, 6],
  #   [6, 7],
  #   [7, 8],
  #   [8, 9],
  # ]

empty

  empty() (Venus::Array)

The empty method drops all elements from the set.

Since 4.11

empty example 1

  # given: synopsis;
  my $empty = $set->empty;
  # bless({}, "Venus::Set")

exists

  exists(number $index) (boolean)

The exists method returns true if the element at the index specified exists, otherwise it returns false.

Since 4.11

exists example 1

  # given: synopsis;
  my $exists = $set->exists(0);
  # true

first

  first() (any)

The first method returns the value of the first element.

Since 4.11

first example 1

  # given: synopsis;
  my $first = $set->first;
  # 1

get

  get(number $index) (any)

The get method returns the value at the position specified.

Since 4.11

get example 1

  # given: synopsis
  package main;
  my $get = $set->get(0);
  # 1

get example 2

  # given: synopsis
  package main;
  my $get = $set->get(3);
  # 4

grep

  grep(coderef $code) (arrayref)

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

  # given: synopsis;
  my $grep = $set->grep(sub {
    $_ > 3
  });
  # [4..9]

grep example 2

  # given: synopsis;
  my $grep = $set->grep(sub {
    my ($key, $value) = @_;
    $value > 3
  });
  # [4..9]

intersect

  intersect(arrayref | Venus::Array | Venus::Set $data) (boolean)

The intersect method returns true if the values provided already exist in the source.

Since 4.11

intersect example 1

  # given: synopsis
  package main;
  my $intersect = $set->intersect([9, 10]);
  # true

intersect example 2

  # given: synopsis
  package main;
  my $intersect = $set->intersect([10, 11]);
  # false

intersection

  intersection(arrayref | Venus::Array | Venus::Set $data) (Venus::Set)

The intersection method returns a new set containing only the values that already exist in the source.

Since 4.11

intersection example 1

  # given: synopsis
  package main;
  $set->push(10);
  my $intersection = $set->intersection([9, 10, 11]);
  # bless(..., "Venus::Set")
  # $intersection->list;
  # [9, 10]

intersection example 2

  # given: synopsis
  package main;
  $set->push(10);
  my $intersection = $set->intersection(Venus::Set->new([9, 10, 11]));
  # bless(..., "Venus::Set")
  # $intersection->list;
  # [9, 10]

intersection example 3

  # given: synopsis
  package main;
  use Venus::Array;
  $set->push(10);
  my $intersection = $set->intersection(Venus::Array->new([9, 10, 11]));
  # bless(..., "Venus::Set")
  # $intersection->list;
  # [9, 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 = $set->iterator;
  # sub { ... }
  # while (my $value = $iterator->()) {
  #   say $value; # 1
  # }

iterator example 2

  # given: synopsis;
  my $iterator = $set->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

  # given: synopsis;
  my $join = $set->join;
  # 123456789

join example 2

  # given: synopsis;
  my $join = $set->join(', ');
  # "1, 2, 3, 4, 5, 6, 7, 8, 9"

keyed

  keyed(string @keys) (hashref)

The keyed method returns a hash reference where the arguments become the keys, and the elements of the array become the values.

Since 4.11

keyed example 1

  package main;
  use Venus::Array;
  my $set = Venus::Array->new([1..4]);
  my $keyed = $set->keyed('a'..'d');
  # { a => 1, b => 2, c => 3, d => 4 }

keys

  keys() (arrayref)

The keys method returns an array reference consisting of the indicies of the array.

Since 4.11

keys example 1

  # given: synopsis;
  my $keys = $set->keys;
  # [0..8]

last

  last() (any)

The last method returns the value of the last element in the array.

Since 4.11

last example 1

  # given: synopsis;
  my $last = $set->last;
  # 9

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

length example 1

  # given: synopsis;
  my $length = $set->length;
  # 9

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

  # given: synopsis;
  my $list = $set->list;
  # 9

list example 2

  # given: synopsis;
  my @list = $set->list;
  # (1..9)

map

  map(coderef $code) (arrayref)

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

  # given: synopsis;
  my $map = $set->map(sub {
    $_ * 2
  });
  # [2, 4, 6, 8, 10, 12, 14, 16, 18]

map example 2

  # given: synopsis;
  my $map = $set->map(sub {
    my ($key, $value) = @_;
    [$key, ($value * 2)]
  });
  # [
  #   [0, 2],
  #   [1, 4],
  #   [2, 6],
  #   [3, 8],
  #   [4, 10],
  #   [5, 12],
  #   [6, 14],
  #   [7, 16],
  #   [8, 18],
  # ]

merge

  merge(any @data) (Venus::Set)

The merge method merges the arguments provided with the existing set.

Since 4.11

merge example 1

  # given: synopsis;
  my $merge = $set->merge(6..9);
  # bless(..., "Venus::Set")
  # $set->list;
  # [1..9]

merge example 2

  # given: synopsis;
  my $merge = $set->merge(8, 10);
  # bless(..., "Venus::Set")
  # $set->list;
  # [1..10]

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 1

  # given: synopsis;
  my $none = $set->none(sub {
    $_ < 1
  });
  # 1

none example 2

  # given: synopsis;
  my $none = $set->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 1

  # given: synopsis;
  my $one = $set->one(sub {
    $_ == 1
  });
  # 1

one example 2

  # given: synopsis;
  my $one = $set->one(sub {
    my ($key, $value) = @_;
    $value == 1
  });
  # 1

order

  order(number @indices) (Venus::Array)

The order method reorders the array items based on the indices provided and returns the invocant.

Since 4.11

order example 1

  # given: synopsis;
  my $order = $set->order;
  # bless(..., "Venus::Set")
  # $set->list;
  # [1..9]

order example 2

  # given: synopsis;
  my $order = $set->order(8,7,6);
  # bless(..., "Venus::Set")
  # $set->list;
  # [9,8,7,1,2,3,4,5,6]

order example 3

  # given: synopsis;
  my $order = $set->order(0,2,1);
  # bless(..., "Venus::Set")
  # $set->list;
  # [1,3,2,4,5,6,7,8,9]

pairs

  pairs() (arrayref)

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

  # given: synopsis;
  my $pairs = $set->pairs;
  # [
  #   [0, 1],
  #   [1, 2],
  #   [2, 3],
  #   [3, 4],
  #   [4, 5],
  #   [5, 6],
  #   [6, 7],
  #   [7, 8],
  #   [8, 9],
  # ]

part

  part(coderef $code) (tuple[arrayref, arrayref])

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

  # given: synopsis;
  my $part = $set->part(sub {
    $_ > 5
  });
  # [[6..9], [1..5]]

part example 2

  # given: synopsis;
  my $part = $set->part(sub {
    my ($key, $value) = @_;
    $value < 5
  });
  # [[1..4], [5..9]]

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

  # given: synopsis;
  my $pop = $set->pop;
  # 9

push

  push(any @data) (arrayref)

The push method appends the array by pushing the agruments onto it and returns itself.

Since 4.11

push example 1

  # given: synopsis;
  my $push = $set->push(10);
  # [1..10]

random

  random() (any)

The random method returns a random element from the array.

Since 4.11

random example 1

  # given: synopsis;
  my $random = $set->random;
  # 2
  # my $random = $set->random;
  # 1

range

  range(number | string @args) (arrayref)

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 1

  # given: synopsis
  package main;
  my $range = $set->range;
  # []

range example 2

  # given: synopsis
  package main;
  my $range = $set->range(0);
  # [1]

range example 3

  # given: synopsis
  package main;
  my $range = $set->range('0:');
  # [1..9]

range example 4

  # given: synopsis
  package main;
  my $range = $set->range(':4');
  # [1..5]

range example 5

  # given: synopsis
  package main;
  my $range = $set->range('8:');
  # [9]

range example 6

  # given: synopsis
  package main;
  my $range = $set->range('4:');
  # [5..9]

range example 7

  # given: synopsis
  package main;
  my $range = $set->range('0:2');
  # [1..3]

range example 8

  # given: synopsis
  package main;
  my $range = $set->range('2:4');
  # [3..5]

range example 9

  # given: synopsis
  package main;
  my $range = $set->range(0..3);
  # [1..4]

range example 10

  # given: synopsis
  package main;
  my $range = $set->range('-1:8');
  # [9,1..9]

range example 11

  # given: synopsis
  package main;
  my $range = $set->range('0:8');
  # [1..9]

range example 12

  # given: synopsis
  package main;
  my $range = $set->range('0:-2');
  # [1..7]

range example 13

  # given: synopsis
  package main;
  my $range = $set->range('-2:-2');
  # [8]

range example 14

  # given: synopsis
  package main;
  my $range = $set->range('0:-20');
  # []

range example 15

  # given: synopsis
  package main;
  my $range = $set->range('-2:-20');
  # []

range example 16

  # given: synopsis
  package main;
  my $range = $set->range('-2:-6');
  # []

range example 17

  # given: synopsis
  package main;
  my $range = $set->range('-2:-8');
  # []

range example 18

  # given: synopsis
  package main;
  my $range = $set->range('-2:-9');
  # []

range example 19

  # given: synopsis
  package main;
  my $range = $set->range('-5:-1');
  # [5..9]

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

  # given: synopsis;
  my $reverse = $set->reverse;
  # [9, 8, 7, 6, 5, 4, 3, 2, 1]

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

  # given: synopsis;
  my $rotate = $set->rotate;
  # [2..9, 1]

rsort

  rsort() (arrayref)

The rsort method returns an array reference containing the values in the array sorted alphanumerically in reverse.

Since 4.11

rsort example 1

  # given: synopsis;
  my $rsort = $set->rsort;
  # [9, 8, 7, 6, 5, 4, 3, 2, 1]

set

  set(any $value) (any)

The set method inserts a new value into the set if it doesn't exist.

Since 4.11

set example 1

  # given: synopsis
  package main;
  $set = $set->set(10);
  # 10

set example 2

  # given: synopsis
  package main;
  $set = $set->set(0);
  # 0

shift

  shift() (any)

The shift method returns the first element of the array shortening it by one.

Since 4.11

shift example 1

  # given: synopsis;
  my $shift = $set->shift;
  # 1

shuffle

  shuffle() (arrayref)

The shuffle method returns an array with the items in a randomized order.

Since 4.11

shuffle example 1

  # given: synopsis
  package main;
  my $shuffle = $set->shuffle;
  # [4, 5, 8, 7, 2, 9, 6, 3, 1]

slice

  slice(string @keys) (arrayref)

The slice method returns a hash reference containing the elements in the array at the index(es) specified in the arguments.

Since 4.11

slice example 1

  # given: synopsis;
  my $slice = $set->slice(2, 4);
  # [3, 5]

sort

  sort() (arrayref)

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::Set;
  my $set = Venus::Set->new(['d','c','b','a']);
  my $sort = $set->sort;
  # ["a".."d"]

subset

  subset(arrayref | Venus::Array | Venus::Set $data) (boolean)

The subset method returns true if all the values provided already exist in the source.

Since 4.11

subset example 1

  # given: synopsis
  package main;
  my $subset = $set->subset([1..4]);
  # true

subset example 2

  # given: synopsis
  package main;
  my $subset = $set->subset([1..10]);
  # false

subset example 3

  # given: synopsis
  package main;
  my $subset = $set->subset([1..9]);
  # true

superset

  superset(arrayref | Venus::Array | Venus::Set $data) (boolean)

The superset method returns true if all the values in the source exists in the values provided.

Since 4.11

superset example 1

  # given: synopsis
  package main;
  my $superset = $set->superset([1..10]);
  # true

superset example 2

  # given: synopsis
  package main;
  my $superset = $set->superset([1..9]);
  # false

superset example 3

  # given: synopsis
  package main;
  my $superset = $set->superset([0..9]);
  # true

unique

  unique() (arrayref)

The unique method returns an array reference consisting of the unique elements in the array.

Since 4.11

unique example 1

  package main;
  use Venus::Set;
  my $set = Venus::Set->new([1,1,1,1,2,3,1]);
  my $unique = $set->unique;
  # [1, 2, 3]

unshift

  unshift(any @data) (arrayref)

The unshift method prepends the array by pushing the agruments onto it and returns itself.

Since 4.11

unshift example 1

  # given: synopsis;
  my $unshift = $set->unshift(-2,-1,0);
  # [-2..9]

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.