NAME

Util::Underscore::Scalars - Functions for introspecting and manipulating scalars

VERSION

version v1.4.2

FUNCTION REFERENCE

$scalar = _::new_dual $num, $str

Creates a new dualvar with numeric value $num and string value $str.

In Perl, scalars contain both a numeric value and a string value. Usually, Perl freely converts between the two values. A dualvar disables the syncing between the two values, so that the string value and the numeric value can be completely unrelated.

wrapper for Scalar::Util::dualvar

$num: the value for the numeric slot

$str: the value for the string slot

returns: a new dualvar

$bool = _::is_dual $scalar

$bool = _::is_dual

Checks whether the given scalar is a dualvar.

wrapper for Scalar::Util::isdual

$scalar: the scalar to check. If omitted, uses $_.

returns: a boolean value indicating whether the $scalar is a dualvar.

$bool = _::is_vstring $scalar

$bool = _::is_vstring

Checks whether the given $scalar was created as a v-string like v127.0.0.1 or v1.0.3.

wrapper for Scalar::Util::isvstring

$scalar: the scalar to check. If omitted, uses $_.

returns: a boolean value indicating whether the $scalar is a v-string.

_::const LVALUE => VALUE

Creates a readonly variable containing the specified value.

Note that this makes a deep immutable copy of the value instead of only disallowing reassignment. This works for scalars, arrays, and hashes. Certain care has to be taken for hashes because this locks the keys, and using an illegal key would blow up with an error. Therefore: always use exists $hash{$key} to see whether a key exists.

Examples:

    _::const my $const => 42;
    _::const my @const => 1, 2, 3;
    _::const my %const => a => 1, b => 2;

Wrapper for const from Const::Fast.

LVALUE: an lvalue (scalar, hash, or array variable) to make constant.

VALUE: the value to make deeply immutable and assign. The expression is always evaluated in list context, but the length of the resulting list must match the lvalue type.

returns: n/a

$bool = _::is_readonly $scalar

$bool = _::is_readonly

Checks whether the given scalar is readonly, i.e. can't be reassigned.

wrapper for Scalar::Util::readonly

$scalar: the scalar to check for readonlyness. If omitted, uses $_.

returns: a boolean indicating whether the $scalar is readonly.

$bool = _::is_tainted $scalar

$bool = _::is_tainted

Checks whether the $scalar is tainted.

Tainted values come from untrusted sources, such as user input, environment variables, or file contents. The result of a computation with tainted values is itself tainted. Tainting is only traced when requested via the -t or -T command line switch. If activated, certain builtins will refuse to execute with tainted input, such as open or system. See perlsec for more information.

wrapper for Scalar::Util::tainted

$scalar: the scalar to check for taintedness. If omitted, uses $_.

returns: a boolean indicating whether the $scalar is tainted.

_::alias my $alias = $orig

Aliases the first variable to the second scalar, unlike normal assignment which assigns a copy.

Afterwards, the $alias will be another name for the $orig scalar, so \$alias == \$orig will always be true. As the same scalar is now accessible by two names, changes are also visible under the other name.

Aliases occur naturally with the for, map, and grep builtins:

    my @values = qw(a b c);
    for (@values) {
        # now $_ is an alias for the current element
        $_ = 42;
    }
    # @values = (42, 42, 42)

but also with subroutine parameters:

    sub assign {
        # the values in @_ are aliases for the arguments
        $_[0] = $_[1];
        return;
    }

    my $x = "foo";
    assign $x => "bar";
    # $x = "bar"

This function is an alias (heh) for the functionality in Data::Alias.

Only available if Data::Alias is already installed. Since Data::Alias has problems with some perl versions, it is not a required dependency.

$alias: an additional name for the $orig scalar.

$orig: The alias target.

returns: n/a

$bool = _::is_plain $scalar

$bool = _::is_plain

Checks that the value is defined and not a reference of any kind.

This is as close as Perl gets to checking for an ordinary string.

$scalar: the scalar to check. If omitted, uses $_.

returns: a boolean indicating whether the scalar is plain.

$bool = _::is_string $scalar

$bool = _::is_string

Checks that the value is intended to be usable as a string: Either _::is_plain returns true, or it is an object that has overloaded stringification.

This does not test that the scalar has ever been used as a string, or was assigned as a string, only that it can be used as a string. Note that some data structures (like references) do have a stringification, but this is rarely intended to be actually used and therefore rejected.

$scalar: the scalar to check for stringiness.

returns: a boolean indicating whether the scalar is string-like.

$bool = _::is_bool $scalar

$bool = _::is_bool

Checks that the value is intended to be usable as a boolean: The argument can either be a non-reference (i.e. plain scalar or undef), or can be an object that overloads bool.

This does not check that the argument is some specific value such as 1 or 0. Note also that any value will be interpreted as a boolean by Perl, but not by this function. For example plain references are true-ish, while this function would not consider them to be a valid boolean value.

$scalar: the scalar to check. If omitted, uses $_.

returns: a boolean indicating whether the given $scalar can be considered to be a boolean by the rules of this function.

$bool = _::is_identifier $string

$bool = _::is_identifier

Checks that the given string would be a legal identifier: a letter followed by zero or more word characters.

$string: a string possibly containing an identifier.

returns: a boolean indicating whether the string looks like an identifier.

$bool = _::is_package $string

$bool = _::is_package

Checks that the given string is a valid package name. It only accepts Foo::Bar notation, not the Foo'Bar form. This does not assert that the package actually exists.

$string: a string possibly containing a package name.

returns: a boolean indicating whether the given string looks like a package name.

$str = _::chomp

$str = _::chomp $line

$str = _::chomp $line, $end

$str_array = _::chomp \@lines

$str_array = _::chomp \@lines, $end

Performs the chomp builtin on a copy of the input – this will not modify the input.

$line, \@lines: a string or a reference to an array of strings. These will not be modified. If omitted, uses $_.

$end: a string designating the input record separator. If not specified, uses $/.

returns: If given a single $line, returns a copy of that string with the end removed. If given multiple \@lines, returns an array reference containing copies of the input lines, with the $end removed from each copy.

Examples:

    # assuming the default $/ = "\n":
    _::chomp ["foo\n", "bar", "baz\n"];
    #=> ["foo", "bar", "baz"]
    
    # removing a custom terminator:
    _::chomp "foobar", "bar";
    #=> "foo"

$pos = _::index $haystack, $needle

$pos = _::index $haystack, $needle, $start

Wraps the builtin index function to return undef rather than -1 if the $needle wasn't found in the $haystack.

$haystack: a string in which to search.

$needle: a string for which to search.

$start: the position at which to start searching. This must be a non-negative integer. Defaults to zero.

returns: The position at which the $needle was found in the $haystack, If no match was found, returns undef.

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/latk/p5-Util-Underscore/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

Lukas Atkinson (cpan: AMON) <amon@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Lukas Atkinson.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.