"""
Overview:
Useful utilities for pluralize your words.
"""
import warnings
from functools import lru_cache
from typing import Optional
try:
import inflect
except ImportError:
from ..system import pip_install
pip_install(['inflect>=5.2.0'], silent=True)
import inflect
__all__ = ['plural_form', 'plural_word', 'singular_form']
@lru_cache()
def _default_engine():
return inflect.engine()
[docs]def plural_word(count: int, word: str,
num_text: bool = False, num_threshold: Optional[int] = None,
engine: Optional[inflect.engine] = None) -> str:
"""
Overview:
Get plural form of the whole word, with the number before the word.
Arguments:
- count (:obj:`int`): Count of the word, should be a non-negative integer.
- word (:obj:`str`): Word to be pluralized.
- num_text (:obj:`bool`): Show the number as text format or not, \
default is ``False`` which means just use the arabic number for all the cases.
- num_threshold (:obj:`Optional[int]`): Threshold value when the number is shown as text, \
default is ``None`` which means just use english text format for all the cases.
- engine (:obj:`Optional[inflect.engine]`): Engine to be used, \
default is ``None`` which means just use the default one.
Returns:
- plural_word (:obj:`str`): Pluralized word, with the number.
Examples::
>>> from hbutils.string import plural_word
>>> plural_word(0, 'word')
'0 words'
>>> plural_word(1, 'word')
'1 word'
>>> plural_word(2, 'word')
'2 words'
>>> plural_word(20, 'word')
'20 words'
>>> plural_word(233, 'word')
'233 words'
>>> plural_word(20, 'word', num_text=True)
'twenty words'
>>> plural_word(233, 'word', num_text=True)
'two hundred and thirty-three words'
>>> plural_word(20, 'word', num_text=True, num_threshold=99)
'twenty words'
>>> plural_word(233, 'word', num_text=True, num_threshold=99)
'233 words'
"""
engine = engine or _default_engine()
if num_text:
number = engine.number_to_words(count, threshold=num_threshold)
else:
if num_threshold is not None:
warnings.warn(UserWarning('Text-formatted number is not enabled, '
'so the num_threshold argument will be ignored.'), stacklevel=2)
number = str(count)
single_word = singular_form(word, engine)
final_word = engine.plural(single_word, count)
return f'{number} {final_word}'