tnum 0.2.0
A Python library for converting between English, Tibetan, and Roman numerals
License: MIT
Requires Python: >=3.7
Keywords: tibetan, roman, numerals, numbers, unicode, conversion

# tnum - Number Conversion Library

A Python library for converting between English numerals (0-9), Tibetan numerals (༠-༩), and Roman numerals (I, V, X, L, C, D, M).

## Features

- Convert English numbers to Tibetan numerals
- Convert Tibetan numerals to English numbers
- Convert English numbers to Roman numerals
- Convert Roman numerals to English numbers
- Convert Tibetan numerals to Roman numerals
- Convert Roman numerals to Tibetan numerals
- Check if a character or string is a Tibetan/English/Roman digit/number
- Support for negative numbers (Tibetan and English)
- Clean, simple API

## Installation

```bash
pip install tnum
```

Or install from source:

```bash
git clone <repository-url>
cd tnum
pip install -e .
```

## Quick Start

```python
from tnum import to_tibetan, from_tibetan, to_roman, from_roman, tibetan_to_roman, roman_to_tibetan

# Convert English to Tibetan
tibetan = to_tibetan(123)
print(tibetan)  # Output: ༡༢༣

# Convert Tibetan to English string
english = from_tibetan("༡༢༣")
print(english)  # Output: "123"

# Convert English to Roman
roman = to_roman(1994)
print(roman)  # Output: "MCMXCIV"

# Convert Roman to English
number = from_roman("MCMXCIV")
print(number)  # Output: 1994

# Convert Tibetan to Roman
roman = tibetan_to_roman("༡༩༩༤")
print(roman)  # Output: "MCMXCIV"

# Convert Roman to Tibetan
tibetan = roman_to_tibetan("MCMXCIV")
print(tibetan)  # Output: "༡༩༩༤"
```

## API Reference

### Tibetan Numerals

#### `to_tibetan(number)`

Convert an English number to Tibetan numerals.

**Parameters:**
- `number` (int or str): An integer or string of English digits

**Returns:**
- `str`: The number represented in Tibetan numerals

**Examples:**
```python
to_tibetan(123)      # Returns: "༡༢༣"
to_tibetan("456")    # Returns: "༤༥༦"
to_tibetan(0)        # Returns: "༠"
to_tibetan(-42)      # Returns: "-༤༢"
```

#### `from_tibetan(tibetan_str)`

Convert Tibetan numerals to an English number string.

**Parameters:**
- `tibetan_str` (str): A string containing Tibetan numerals

**Returns:**
- `str`: The number as a string of English digits

**Examples:**
```python
from_tibetan("༡༢༣")    # Returns: "123"
from_tibetan("༤༥༦")    # Returns: "456"
from_tibetan("-༡༢")    # Returns: "-12"
```

#### `to_tibetan_int(tibetan_str)`

Convert Tibetan numerals to a Python integer.

**Parameters:**
- `tibetan_str` (str): A string containing Tibetan numerals

**Returns:**
- `int`: The number as a Python integer

**Examples:**
```python
to_tibetan_int("༡༢༣")    # Returns: 123
to_tibetan_int("༤༥༦")    # Returns: 456
```

### Roman Numerals

#### `to_roman(number)`

Convert an integer to Roman numerals.

**Parameters:**
- `number` (int): An integer between 1 and 3999

**Returns:**
- `str`: The number represented in Roman numerals

**Examples:**
```python
to_roman(1)      # Returns: "I"
to_roman(4)      # Returns: "IV"
to_roman(9)      # Returns: "IX"
to_roman(1994)   # Returns: "MCMXCIV"
to_roman(2024)   # Returns: "MMXXIV"
```

#### `from_roman(roman_str)`

Convert Roman numerals to a Python integer.

**Parameters:**
- `roman_str` (str): A string containing Roman numerals

**Returns:**
- `int`: The number as a Python integer

**Examples:**
```python
from_roman("I")        # Returns: 1
from_roman("IV")       # Returns: 4
from_roman("IX")       # Returns: 9
from_roman("MCMXCIV")  # Returns: 1994
```

#### `tibetan_to_roman(tibetan_str)`

Convert Tibetan numerals to Roman numerals.

**Parameters:**
- `tibetan_str` (str): A string containing Tibetan numerals

**Returns:**
- `str`: The number represented in Roman numerals

**Examples:**
```python
tibetan_to_roman("༡")      # Returns: "I"
tibetan_to_roman("༤")      # Returns: "IV"
tibetan_to_roman("༡༩༩༤")  # Returns: "MCMXCIV"
```

#### `roman_to_tibetan(roman_str)`

Convert Roman numerals to Tibetan numerals.

**Parameters:**
- `roman_str` (str): A string containing Roman numerals

**Returns:**
- `str`: The number represented in Tibetan numerals

**Examples:**
```python
roman_to_tibetan("I")        # Returns: "༡"
roman_to_tibetan("IV")       # Returns: "༤"
roman_to_tibetan("MCMXCIV")  # Returns: "༡༩༩༤"
```

### Detection Functions

#### `is_tibetan_digit(char)`

Check if a character is a Tibetan digit.

**Parameters:**
- `char` (str): A single character

**Returns:**
- `bool`: True if the character is a Tibetan digit

**Examples:**
```python
is_tibetan_digit("༡")    # Returns: True
is_tibetan_digit("1")     # Returns: False
```

#### `is_tibetan_number(text)`

Check if a string contains only Tibetan digits.

**Parameters:**
- `text` (str): A string to check

**Returns:**
- `bool`: True if the string contains only Tibetan digits

**Examples:**
```python
is_tibetan_number("༡༢༣")     # Returns: True
is_tibetan_number("123")      # Returns: False
is_tibetan_number("-༡༢༣")    # Returns: True
```

#### `is_english_digit(char)`

Check if a character is an English digit (0-9).

**Parameters:**
- `char` (str): A single character

**Returns:**
- `bool`: True if the character is an English digit

**Examples:**
```python
is_english_digit("1")     # Returns: True
is_english_digit("༡")     # Returns: False
is_english_digit("a")     # Returns: False
```

#### `is_english_number(text)`

Check if a string contains only English digits.

**Parameters:**
- `text` (str): A string to check

**Returns:**
- `bool`: True if the string contains only English digits

**Examples:**
```python
is_english_number("123")      # Returns: True
is_english_number("༡༢༣")     # Returns: False
is_english_number("-123")     # Returns: True
is_english_number("12.34")    # Returns: False
```

#### `is_roman_numeral(text)`

Check if a string is a valid Roman numeral.

**Parameters:**
- `text` (str): A string to check

**Returns:**
- `bool`: True if the string is a valid Roman numeral

**Examples:**
```python
is_roman_numeral("IV")        # Returns: True
is_roman_numeral("MCMXCIV")   # Returns: True
is_roman_numeral("123")       # Returns: False
is_roman_numeral("IIII")      # Returns: False (invalid format)
```

## Number Systems

### Tibetan Numerals

The library supports the standard Tibetan numeral system:

| English | Tibetan | Unicode |
|---------|---------|---------|
| 0       | ༠       | U+0F20  |
| 1       | ༡       | U+0F21  |
| 2       | ༢       | U+0F22  |
| 3       | ༣       | U+0F23  |
| 4       | ༤       | U+0F24  |
| 5       | ༥       | U+0F25  |
| 6       | ༦       | U+0F26  |
| 7       | ༧       | U+0F27  |
| 8       | ༨       | U+0F28  |
| 9       | ༩       | U+0F29  |

### Roman Numerals

The library supports standard Roman numerals (1-3999):

| Value | Roman | Value | Roman | Value | Roman |
|-------|-------|-------|-------|-------|-------|
| 1     | I     | 10    | X     | 100   | C     |
| 4     | IV    | 40    | XL    | 400   | CD    |
| 5     | V     | 50    | L     | 500   | D     |
| 9     | IX    | 90    | XC    | 900   | CM    |
|       |       |       |       | 1000  | M     |

## Examples

### Basic Conversions

```python
from tnum import to_tibetan, from_tibetan, to_roman, from_roman

# Convert various numbers
numbers = [0, 1, 42, 100, 999, 2024]
for num in numbers:
    tibetan = to_tibetan(num)
    roman = to_roman(num) if num > 0 else "N/A"
    print(f"{num} -> Tibetan: {tibetan}, Roman: {roman}")
```

### Working with User Input

```python
from tnum import (
    is_tibetan_number,
    is_english_number,
    is_roman_numeral,
    from_tibetan,
    from_roman,
    to_tibetan,
    to_roman,
)

user_input = input("Enter a number: ")

if is_tibetan_number(user_input):
    english = from_tibetan(user_input)
    print(f"Tibetan {user_input} = English {english}")
elif is_roman_numeral(user_input):
    english = from_roman(user_input)
    print(f"Roman {user_input} = English {english}")
elif is_english_number(user_input):
    num = int(user_input)
    tibetan = to_tibetan(num)
    roman = to_roman(num) if num > 0 else "N/A"
    print(f"English {num} = Tibetan {tibetan}, Roman {roman}")
else:
    print("Invalid input")
```

### Cross-System Conversions

```python
from tnum import to_tibetan, from_tibetan, to_roman, from_roman, tibetan_to_roman, roman_to_tibetan

# Convert between all systems
value = 1994
tibetan = to_tibetan(value)      # "༡༩༩༤"
roman = to_roman(value)          # "MCMXCIV"

# Convert back
english_from_tibetan = from_tibetan(tibetan)  # "1994"
english_from_roman = from_roman(roman)        # 1994

# Direct conversions
roman_from_tibetan = tibetan_to_roman(tibetan)  # "MCMXCIV"
tibetan_from_roman = roman_to_tibetan(roman)  # "༡༩༩༤"
```

## Development

### Running Tests

```bash
pytest
```

### Building the Package

```bash
python -m build
```

## License

MIT License

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## References

- [Tibetan Numerals on Wikipedia](https://en.wikipedia.org/wiki/Tibetan_numerals)
- [Unicode Tibetan Block](https://www.unicode.org/charts/PDF/U0F00.pdf)
- [Roman Numerals on Wikipedia](https://en.wikipedia.org/wiki/Roman_numerals)