NAME
    Unicode::Util - Unicode-aware versions of built-in Perl functions

VERSION
    This document describes Unicode::Util version 0.06.

SYNOPSIS
        use Unicode::Util qw( graph_length code_length byte_length );

        # grapheme cluster ю́: Cyrillic small letter yu + combining acute accent
        my $grapheme = "\x{44E}\x{301}";

        say graph_length($grapheme);          # 1
        say code_length($grapheme);           # 2
        say byte_length($grapheme, 'UTF-8');  # 4

DESCRIPTION
    This module provides Unicode-aware versions of Perl’s built-in string
    functions, tailored to work on grapheme clusters as opposed to code
    points or bytes.

FUNCTIONS
    Functions may each be exported explicitly, or by using the ":all" tag
    for everything or the ":length" tag for the length functions.

    graph_length($string)
        Returns the length of the given string in grapheme clusters. This is
        the closest to the number of “characters” that many people would
        count on a printed string.

    code_length($string)
    code_length($string, $normal_form)
        Returns the length of the given string in code points. This is
        likely the number of “characters” that many programmers and
        programming languages would count in a string. If the optional
        Unicode normalization form is supplied, the length will be of the
        string as if it had been normalized to that form.

        Valid normalization forms are "C" or "NFC", "D" or "NFD", "KC" or
        "NFKC", and "KD" or "NFKD".

    byte_length($string)
    byte_length($string, $encoding)
    byte_length($string, $encoding, $normal_form)
        Returns the length of the given string in bytes, as if it were
        encoded using the specified encoding or UTF-8 if no encoding is
        supplied. If the optional Unicode normalization form is supplied,
        the length will be of the string as if it had been normalized to
        that form.

    graph_chop($string)
        Returns the given string with the last grapheme cluster chopped off.
        Does not modify the original value, unlike the built-in "chop".

    graph_reverse($string)
        Returns the given string value with all grapheme clusters in the
        opposite order.

TODO
    "graph_substr", "graph_index", "graph_rindex"

SEE ALSO
    Unicode::GCString, String::Multibyte, Perl6::Str,
    <http://perlcabal.org/syn/S32/Str.html>

AUTHOR
    Nick Patch <patch@cpan.org>

COPYRIGHT AND LICENSE
    © 2011–2012 Nick Patch

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