| single |
|pypi_downloads| |codecov| |license|
============
Introduction
============
This library is mainly for CLI programs that carefully produce output for
Terminals, or make pretend to be an emulator.
**Problem Statement**: The printable length of *most* strings are equal to
the
number of cells they occupy on the screen ``1 character : 1 cell``.
However,
there are categories of characters that *occupy 2 cells* (full-wide), and
others that *occupy 0* cells (zero-width).
**Solution**: POSIX.1-2001 and POSIX.1-2008 conforming systems provide
`wcwidth(3)`_ and `wcswidth(3)`_ C functions of which this python module's
functions precisely copy. *These functions return the number of cells a
unicode string is expected to occupy.*
Installation
------------
The stable version of this package is maintained on pypi, install using
pip::
pip install wcwidth
Example
-------
**Problem**: given the following phrase (Japanese),
>>> text = u'コンニチハ'
Python **incorrectly** uses the *string length* of 5 codepoints rather than
the
*printible length* of 10 cells, so that when using the `rjust` function,
the
output length is wrong::
>>> print(len('コンニチハ'))
5
>>> print('コンニチハ'.rjust(20, '_'))
_______________コンニチハ
By defining our own "rjust" function that uses wcwidth, we can correct
this::
>>> def wc_rjust(text, length, padding=' '):
:alt: MIT License
|