**Advanced area**

Included in this section are Perl package functions that are technically available to use in survey code, but are** typically unnecessary**. Readers are advised to exhaust other **built-in IntelliSurvey methods** and solutions before considering these 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".

**Note:** Because Perl treats `undef`

as "false", you __must__ check the return value of `all_u`

with `defined`

or you will get the opposite result of what you expect.

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".

Because Perl treats `undef`

as "false", you __must__ check the return value of `none_u`

with `defined`

or you will get the opposite result of what you expect.

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

## Comments

0 comments

Please sign in to leave a comment.