=begin pod

=head1 NAME

Raku port of Perl's chr() / ord() built-ins

=head1 SYNOPSIS

=begin code :lang<raku>
use P5chr; # exports chr() and ord()

my $a = 65;
say chr $a;

my $a = "A";
say ord $a;
=end code

=head1 DESCRIPTION

This module tries to mimic the behaviour of Perl's C<chr> and C<ord> built-ins
as closely as possible in the Raku Programmming Language.

=head1 ORIGINAL PERL 5 DOCUMENTATION

=begin output
chr NUMBER
chr     Returns the character represented by that NUMBER in the character
        set. For example, "chr(65)" is "A" in either ASCII or Unicode, and
        chr(0x263a) is a Unicode smiley face.

        Negative values give the Unicode replacement character
        (chr(0xfffd)), except under the bytes pragma, where the low eight
        bits of the value (truncated to an integer) are used.

        If NUMBER is omitted, uses $_.

        For the reverse, use "ord".

        Note that characters from 128 to 255 (inclusive) are by default
        internally not encoded as UTF-8 for backward compatibility
        reasons.

ord EXPR
ord     Returns the numeric value of the first character of EXPR. If EXPR
        is an empty string, returns 0. If EXPR is omitted, uses $_. (Note
        character, not byte.)

        For the reverse, see "chr".
=end output

=head1 PORTING CAVEATS

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<chr> or C<ord> has become impossible.  Code such as:

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

should be changed to either:

=begin code :lang<raku>
say chr($_);
=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 .&chr;
=end code

By the way, the Raku built-ins C<chr> and C<ord> subroutines have almost
the same semantics as their Perl counterparts (apart from the topic from
caller feature, which no longer works).  So in most cases it should not
be needed to be using this module at all anymore.

=head1 AUTHOR

Elizabeth Mattijsen <liz@raku.rocks>

Source can be located at: https://github.com/lizmat/P5chr . 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, 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
