=begin pod

=head1 NAME

Raku port of Perl's length() built-in

=head1 SYNOPSIS

=begin code :lang<raku>
use P5length; # exports length()

say length("foobar"); # 6
say length(Str);      # Str

$_ = "foobar";
say .length;           # 6
=end code

=head1 DESCRIPTION

This module tries to mimic the behaviour of Perl's C<length> built-in
as closely as possible in the Raku Programming Language.

=head1 ORIGINAL PERL 5 DOCUMENTATION

=begin output
length EXPR
length  Returns the length in characters of the value of EXPR. If EXPR is
        omitted, returns the length of $_. If EXPR is undefined, returns
        "undef".

        This function cannot be used on an entire array or hash to find
        out how many elements these have. For that, use "scalar @array"
        and "scalar keys %hash", respectively.

        Like all Perl character operations, length() normally deals in
        logical characters, not physical bytes. For how many bytes a
        string encoded as UTF-8 would take up, use
        "length(Encode::encode_utf8(EXPR))" (you'll have to "use Encode"
        first). See Encode and perlunicode.
=end output

=head1 PORTING CAVEATS

=head2 Characters vs codepoints

Since the Perl documentation mentions C<characters> rather than codepoints,
C<length> will return the number of characters, as seen using Normalization
Form Grapheme (NFG).

=head2 Handling of type objects

C<length> in Perl is supposed to return C<undef> when given C<undef>.  Since
undefined values are type objects in Raku, and it looks like C<length> is
simply returning what it was given in the undefined case, it felt appropriate
to simply return the given type object rather than C<Nil>.

=head2 $_ no longer accessible from caller's scope

With the arrival of RakuAST, it has become impossible to access the
topic variable (C<$_>) of the caller's scope.  So Perl's idiom of
calling C<length> without arguments has become impossible.  Code such
as:

=begin code :lang<raku>
say length;
=end code

should be changed to either:

=begin code :lang<raku>
say length($_);
=end code

or, using the subroutine as a method syntax, with the prefix C<.> shortcut
to use that scope's C<$_> as the invocant:

=begin code :lang<raku>
say .&length;
=end code

=head1 AUTHOR

Elizabeth Mattijsen <liz@raku.rocks>

Source can be located at: https://github.com/lizmat/P5length . Comments and
Pull Requests are welcome.

If you like this module, or what I’m doing more generally, committing to a
L<small sponsorship|https://github.com/sponsors/lizmat/>  would mean a great
deal to me!

=head1 COPYRIGHT AND LICENSE

Copyright 2018, 2019, 2020, 2021, 2023, 2026 Elizabeth Mattijsen

Re-imagined from Perl as part of the CPAN Butterfly Plan.

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.

=end pod

# vim: expandtab shiftwidth=4
