NAME
    Text::ANSI::WideUtil - Routines for text containing ANSI color codes
    (wide-character functions only)

VERSION
    This document describes version 0.232 of Text::ANSI::WideUtil (from Perl
    distribution Text-ANSI-WideUtil), released on 2021-04-14.

SYNOPSIS
     use Text::ANSI::WideUtil qw(
                               ta_mbpad
                               ta_mbsubstr
                               ta_mbswidth
                               ta_mbswidth_height
                               ta_mbtrunc
                               ta_mbwrap
                              );

     # calculate visual width of text if printed on terminal (can handle Unicode
     # wide characters and exclude the ANSI color codes)
     say ta_mbswidth("\e[31mred");  # => 3
     say ta_mbswidth("\e[31m红色"); # => 4

     # ditto, but also return the number of lines
     say ta_mbswidth_height("\e[31mred\n红色"); # => [4, 2]

     # wrap text to a certain column width, handle ANSI color codes
     say ta_mbwrap(...);

     # pad (left, right, center) text to a certain width
     say ta_mbpad(...);

     # truncate text to a certain width while still passing ANSI color codes
     say ta_mbtrunc(...);

     # get substring, like ta_substr()
     my $substr = ta_mbsubstr("...", $pos, $len);

     # return text but with substring replaced with replacement
     say ta_mbsubstr("...", $pos, $len, $replacement);

DESCRIPTION
    This module contains the wide-character variant ("ta_mb*()") for some
    functions in Text::ANSI::Util. It is split so only this module requires
    Text::WideChar::Util and Text::ANSI::Util can be kept slim.

FUNCTIONS
  ta_mbpad($text, $width[, $which[, $padchar[, $truncate]]]) => STR
    Pad <$text> to $width. Like "ta_pad()" but it uses "ta_mbswidth()" to
    determine visual width instead of "ta_length()". See documentation for
    "ta_pad()" for more details on the other arguments.

  ta_mbtrunc($text, $width) => STR
    Truncate $text to $width. Like "ta_trunc()" but it uses "ta_mbswidth()"
    to determine visual width instead of "ta_length()".

  ta_mbswidth($text) => INT
    Return visual width of $text (in number of columns) if printed on
    terminal. Equivalent to
    "Text::WideChar::Util::mbswidth(ta_strip($text))". This function can be
    used e.g. in making sure that your text aligns vertically when output to
    the terminal in tabular/table format.

    Note that "ta_mbswidth()" handles multiline text correctly, e.g.:
    "ta_mbswidth("foo\nbarbaz")" gives 6 instead of 3-1+8 = 8. It splits the
    input text first with "/\r?\n/" as separator.

  ta_mbswidth_height($text) => [INT, INT]
    Like "ta_mbswidth()", but also gives height (number of lines). For
    example, "ta_mbswidth_height("西爪哇\nb\n")" gives "[6, 3]".

  ta_mbwrap($text, $width, \%opts) => STR
    Like "ta_wrap()", but it uses "ta_mbswidth()" to determine visual width
    instead of "ta_length()".

    Performance: ~300/s on my Core i5 1.7GHz laptop for a ~1KB of text (with
    zero to moderate amount of color codes). As a comparison,
    Text::WideChar::Util's mbwrap() can do about 650/s.

  ta_mbsubstr($text, $pos, $len[ , $replacement ]) => STR
    Like "ta_substr()", but handles wide characters. $pos is counted in
    visual width, not number of characters.

FAQ
  Why split functionalities of wide character and color support into multiple modules/distributions?
    Performance (see numbers in the function description), dependency
    (Unicode::GCString is used for wide character support), and overhead
    (loading Unicode::GCString).

  How do I truncate string based on number of characters instead of columns?
    You can simply use "ta_trunc()" even on text containing wide characters.
    ta_trunc() uses Perl's length() which works on a per-character basis.

HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/Text-ANSI-WideUtil>.

SOURCE
    Source repository is at
    <https://github.com/perlancar/perl-Text-ANSI-WideUtil>.

BUGS
    Please report any bugs or feature requests on the bugtracker website
    <https://github.com/perlancar/perl-Text-ANSI-WideUtil/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.

SEE ALSO
    Text::ANSI::Util, Text::WideChar::Util, Text::NonWideChar::Util,
    Text::Wrap, String::Pad

    <http://en.wikipedia.org/wiki/ANSI_escape_code>

    CLI's that use functions from this module include: dux from App::dux
    ("dux wrap", "dux lpad", "dux rpad").

AUTHOR
    perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2021, 2020, 2015 by perlancar@cpan.org.

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