Perl package functions

The following Perl functions are currently available for use with the IntelliSurvey programming language.

all / all_u

Returns a "true" value if all items in LIST meet the criterion given through BLOCK. Sets $_ for each item in LIST in turn:

cvalue: return 1 if all { $_ >= 0 } ($Q1R1, $Q1R2, $Q1R3);  # All values are non-negative

Thus, all_u(@list) is equivalent to @list ? all(@list) : undef. For an empty LIST, all returns "true" (i.e. no values failed the condition) and all_u returns "undef".

See https://metacpan.org/pod/List::AllUtils#all-BLOCK-LIST.

any / any_u

Returns a "true" value if any item in LIST meets the criterion given through BLOCK.Sets $_ for each item in LIST in turn:

cvalue: return 1 if any { $_ >= 0 } ($Q1, $Q2, $Q3);  # At least one non-negative value

Thus, any_u(@list) is equivalent to @list ? any(@list) : undef. For an empty LIST, any returns "false" and any_u returns "undef".

See https://metacpan.org/pod/List::AllUtils#any-BLOCK-LIST.

ceil

This is identical to the C function ceil(), returning the smallest integer value greater than or equal to the given numerical argument.

See https://perldoc.perl.org/POSIX.html#FUNCTIONS.

distinct

Returns a new list by stripping duplicate values in LIST by comparing the values as hash keys, except that undef is considered separate from ''. The order of elements in the returned list is the same as in LIST. In scalar context, returns the number of unique elements in LIST.

my @x = uniq 1, 1, 2, 2, 3, 5, 3, 4; # returns 1 2 3 5 4
my $x = uniq 1, 1, 2, 2, 3, 5, 3, 4; # returns 5
# returns "Mike", "Michael", "Richard", "Rick"
my @n = distinct "Mike", "Michael", "Richard", "Rick", "Michael", "Rick"
# returns '', 'S1', A5' and complains about "Use of uninitialized value"
my @s = distinct '', undef, 'S1', 'A5'
# returns undef, 'S1', A5' and complains about "Use of uninitialized value"
my @w = uniq undef, '', 'S1', 'A5'

See https://metacpan.org/pod/List::AllUtils#distinct-LIST.

first_value

Returns the first element in LIST for which BLOCK evaluates to true. Each element of LIST is set to $_ in turn. Returns "undef" if no such element has been found.

See https://metacpan.org/pod/List::AllUtils#first_value-BLOCK-LIST.

floor

This is identical to the C function floor(), returning the largest integer value less than or equal to the given numerical argument.

See https://perldoc.perl.org/POSIX.html#FUNCTIONS.

max

Returns the entry in the list with the highest numerical value. If the list is empty, then "undef" is returned.

cvalue: return max 1..10                # 10
cvalue: return max $Q1, $Q2, $Q3        # find the value of the variable with largest value, e.g. "80"
cvalue: return max @$QCB1, @$QCB2       # find the largest option ID selected at checkbox questions QCB1 and QCB2

This function could be implemented using reduce like this:

$foo = reduce { $a > $b ? $a : $b } 1..10

See https://metacpan.org/pod/List::AllUtils#max-LIST.

min

Similar to max, but returns the entry in the list with the lowest numerical value.If the list is empty, then "undef" is returned.

cvalue: return min 1..10                # 1
cvalue: return min $Q1, $Q2, $Q3        # find the value of the variable with smallest value, e.g. "0.25"
cvalue: return min @$QCB1, @$QCB2       # find the smallest option ID selected at checkbox questions QCB1 and QCB2

This function could be implemented using reduce like this:

$foo = reduce { $a < $b ? $a : $b } 1..10

See https://metacpan.org/pod/List::AllUtils#min-LIST.

none / none_u

Logically the negation of any. Returns a true value if no item in LIST meets the criterion given through BLOCK.Sets $_ for each item in LIST in turn:

cvalue: return 1 if none { $_ < 2 } ($Q1R1, $Q1R2, $Q1R3);  # No values found less than 2

Thus, none_u(@list) is equivalent to @list ? none(@list) : undef. For an empty LIST, none returns "true" (i.e., no values failed the condition) and none_u returns "undef".

See https://metacpan.org/pod/List::AllUtils#none-BLOCK-LIST.

notall / notall_u

Logically the negation of all; returns a "true" value if not all items in LIST meet the criterion given through BLOCK.Sets $_ for each item in LIST in turn:

cvalue: return 1 if notall { $_ >= 0 } ($Q1R1, $Q1R2, $Q1R3);   # Not all values are non-negative (some are negative)

Thus, notall_u(@list) is equivalent to @list ? notall(@list) : undef. For an empty LIST, notall returns "false" and notall_u returns "undef".

See https://metacpan.org/pod/List::AllUtils#notall-BLOCK-LIST.

reduce

Reduces LIST by calling BLOCK, in a scalar context, multiple times, setting $a and $b each time. The first call will be with $a and $b set to the first two elements of the list; subsequent calls will be done by setting $a to the result of the previous call and $b to the next element in the list.Returns the result of the last call to BLOCK. If LIST is empty, then undef is returned. If LIST only contains one element, then that element is returned, and BLOCK is not executed.

$foo = reduce { $a < $b ? $a : $b } 1..10       # same as min
$foo = reduce { $a lt $b ? $a : $b } 'aa'..'zz' # same as minstr
$foo = reduce { $a + $b } 1 .. 10               # same as sum
$foo = reduce { $a . $b } @bar                  # same as concat

The remaining list-reduction functions are all specializations of this generic idea. If your algorithm requires that reduce produce an identity value, then make sure that you always pass that identity value as the first argument to prevent undef being returned.

$foo = reduce { $a + $b } 0, @values;             # sum with 0 identity value

See https://metacpan.org/pod/List::AllUtils#reduce-BLOCK-LIST.

Rounding functions

The following functions are part of the Math::Round module: round, nearest, nearest_ceil, nearest_floor, nhimult, and nlowmult.

For more information on these functions, see https://metacpan.org/pod/Math::Round.

round

Rounds LIST to the nearest integer. To instead round to the nearest value, use one of the nearest functions (nearest, nearest_floor, nearest_ceil), nhimult, or nlowmult. In scalar context, round returns a single value; in list context, it returns a list of values.

For example:

$foo = round(2.5)       # 3
$foo = round(2.25)		# 2
$foo = round(-2.5)		# -3
$foo = round(-2.25)		# -2

The round function may also be used with "scalar" values, such as:

cvalue: round($QA) 		# rounds response from QA to nearest integer

nearest

Rounds the number(s) to the nearest multiple of the target value; the specified target must be positive. In scalar context, it returns a single value; in list context, it returns a list of values.
For example:

$foo = nearest(10, 44)		# 40
$foo = nearest(10, 46)		# 50
$foo = nearest(10, 45)		# 45
$foo = nearest(25, 328)		# 325
$foo = nearest(.1, 4.567)	# 4.6
$foo = nearest(10, -45)		# -50

The nearest function may also be used with "scalar" values, such as:

cvalue: nearest(3, $QA) 		# rounds response from QA to nearest multiple of 3

nearest_ceil / nearest_floor

It is possible to force values halfway between two multiples of a target to be rounded to the "floor" (rounded down to the nearest multiple) or "ceiling" (rounded up to the nearest multiple). Use either nearest_floor or nearest_ceil, respectively.

$foo = nearest_ceil(10, 44)		# 40
$foo = nearest_ceil(10, 45)     # 50
$foo = nearest_ceil(10, -45)    # -40

$foo = nearest_floor(10, 44)    # 40
$foo = nearest_floor(10, 45)    # 40
$foo = nearest_floor(10, -45)   # -50

The nearest_ceil and nearest_floor functions may also be used with "scalar" values, such as:

cvalue: nearest_ceil(0.25, $QA) 		# rounds response to nearest 0.25; if halfway between, will round up

cvalue: nearest_floor(0.25, $QA) 		# rounds response to nearest 0.25; if halfway between, will round dowwn

nhimult / nlowmult

Rounds the number(s) to the nearest multiple of the target value, with nhimult rounding the next higher multiple and nlowmult rounding to the next lower multiple. The specified target must be positive. In scalar context, nhimult and nlowmult return a single value; in list context, they return a list of values.

For example:

$foo = nhimult(10, 44)		# 50
$foo = nhimult(10, 46)      # 50
$foo = nhimult(25, 328)     # 350
$foo = nhimult(.1, 4.512)   # 4.6
$foo = nhimult(10, -49)     # -40

$foo = nlowmult(10, 44)     # 40
$foo = nlowmult(10, 46)     # 40
$foo = nlowmult(25, 328)    # 325
$foo = nlowmult(.1, 4.567)  # 4.5
$foo = nlowmult(10, -41)    # -50

The nhimult and nlowmult functions may also be used with "scalar" values, such as:

cvalue: nhimult(3, $QA)		# rounds to next higher multiple of 3

cvalue: nlowmult(3, $QA)	# rounds to next lower multiple of 3

sum

Returns the sum of all the elements in LIST. If LIST is empty, then undef is returned.

$foo = sum 1..10                # 55
$foo = sum 3,9,12               # 24
$foo = sum @bar, @baz           # whatever

This function could be implemented using reduce like this

$foo = reduce { $a + $b } 1..10

See https://metacpan.org/pod/List::AllUtils#sum-LIST.