Merge pull request #40 from gunthercox/decimal

Add support for "point" as a binary word operator

Author: gunthercox

docs/advanced.rst

@@ -64,6 +64,9 @@ mathparse supports unary functions that operate on a single value:
    * - log
      - Base-10 logarithm
      - ``mathparse.parse('log 100')`` → 2.0
+   * - neg
+     - Negative (unary minus)
+     - ``mathparse.parse('negative five', language='ENG')`` → -5
 
 **Examples:**
 

docs/examples.rst

@@ -275,6 +275,90 @@ Word-Based Function Examples
     result = mathparse.parse('three squared times two', language='ENG')
     print(result)  # 18
 
+Decimal Numbers
+---------------
+
+Word-Based Decimal Numbers
+++++++++++++++++++++++++++
+
+mathparse supports parsing decimal numbers expressed in words using the word "point" (or equivalent in other languages).
+The decimal point is treated as a binary operator that combines the integer and fractional parts.
+
+English Decimal Examples
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    from mathparse import mathparse
+
+    # Simple decimal numbers
+    result = mathparse.parse('five point two', language='ENG')
+    print(result)  # 5.2
+
+    result = mathparse.parse('ten point twenty five', language='ENG')
+    print(result)  # 10.25
+
+    result = mathparse.parse('fifty three point four', language='ENG')
+    print(result)  # 53.4
+
+    # Decimal numbers in expressions
+    result = mathparse.parse('five point two plus three', language='ENG')
+    print(result)  # 8.2
+
+    result = mathparse.parse('fifty three point four times seven', language='ENG')
+    print(result)  # 373.8
+
+    result = mathparse.parse('three point five plus two point one', language='ENG')
+    print(result)  # 5.6
+
+    result = mathparse.parse('twenty one point six divided by four', language='ENG')
+    print(result)  # 5.4
+
+French Decimal Examples
+~~~~~~~~~~~~~~~~~~~~~~~
+
+In French, the word "virgule" (comma) is used for decimal points:
+
+.. code-block:: python
+
+    # French decimal numbers
+    result = mathparse.parse('cinq virgule deux', language='FRE')
+    print(result)  # 5.2
+
+    result = mathparse.parse('dix virgule vingt cinq', language='FRE')
+    print(result)  # 10.25
+
+Spanish Decimal Examples
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+In Spanish, the word "punto" is used for decimal points:
+
+.. code-block:: python
+
+    # Spanish decimal numbers
+    result = mathparse.parse('cinco punto dos', language='ESP')
+    print(result)  # 5.2
+
+    result = mathparse.parse('diez punto veinticinco', language='ESP')
+    print(result)  # 10.25
+
+Numeric Decimal Support
++++++++++++++++++++++++
+
+mathparse also supports standard numeric decimal notation:
+
+.. code-block:: python
+
+    # Numeric decimals
+    result = mathparse.parse('5.2')
+    print(result)  # 5.2
+
+    result = mathparse.parse('53.4 * 7')
+    print(result)  # 373.8
+
+    result = mathparse.parse('3.5 + 2.1')
+    print(result)  # 5.6
+
 Practical Use Cases
 -------------------
 
@@ -324,10 +408,10 @@ Natural Language Processing
         try:
             # Extract the mathematical expression
             expression = mathparse.extract_expression(sentence, language)
-            
+
             # Parse and calculate
             result = mathparse.parse(expression, language=language)
-            
+
             return {
                 'original': sentence,
                 'extracted': expression,
@@ -359,18 +443,18 @@ Unit Conversion Helper
 
     def convert_units():
         """Examples of using mathparse for unit conversions."""
-        
+
         # Temperature conversion: Celsius to Fahrenheit
         # F = C * 9/5 + 32
         celsius = 25
         fahrenheit = mathparse.parse(f'{celsius} * 9 / 5 + 32')
         print(f"{celsius}°C = {fahrenheit}°F")  # 25°C = 77.0°F
-        
+
         # Area of circle: π * r²
         radius = 5
         area = mathparse.parse(f'pi * {radius} * {radius}')
         print(f"Circle area (r={radius}): {area}")  # Circle area (r=5): 78.54225
-        
+
         # Compound interest: P * (1 + r)^t
         principal = 1000
         rate = 0.05  # 5%
@@ -392,13 +476,13 @@ Educational Applications
             ("What is deux plus trois?", 'FRE', 5),  # French
             ("Calculate fünf mal sechs", 'GER', 30),  # German
         ]
-        
+
         for question, lang, expected in questions:
             try:
                 # Extract and solve
                 expression = mathparse.extract_expression(question, lang)
                 result = mathparse.parse(expression, language=lang)
-                
+
                 correct = "✓" if result == expected else "✗"
                 print(f"{correct} {question}")
                 print(f"   Expression: {expression}")
@@ -456,13 +540,13 @@ Robust Error Handling
         """Safely parse expressions with comprehensive error handling."""
         try:
             result = mathparse.parse(expression, language=language)
-            
+
             # Check for division by zero
             if result == 'undefined':
                 return {'success': False, 'error': 'Division by zero', 'result': default}
-            
+
             return {'success': True, 'result': result}
-            
+
         except InvalidLanguageCodeException:
             return {'success': False, 'error': 'Invalid language code', 'result': default}
         except PostfixTokenEvaluationException as e:
@@ -492,20 +576,22 @@ Benchmarking Example
     from mathparse import mathparse
 
     def benchmark_parsing():
-        """Compare performance of numeric vs word-based parsing."""
-        
+        """
+        Compare performance of numeric vs word-based parsing.
+        """
+
         # Numeric expressions (faster)
         start_time = time.time()
         for i in range(1000):
             result = mathparse.parse('2 + 3 * 4')
         numeric_time = time.time() - start_time
-        
+
         # Word-based expressions (slower due to text processing)
         start_time = time.time()
         for i in range(1000):
             result = mathparse.parse('two plus three times four', language='ENG')
         word_time = time.time() - start_time
-        
+
         print(f"Numeric parsing: {numeric_time:.4f}s for 1000 operations")
         print(f"Word-based parsing: {word_time:.4f}s for 1000 operations")
         print(f"Word-based is {word_time/numeric_time:.1f}x slower")
@@ -541,22 +627,22 @@ Optimization Tips
     def batch_parse(expressions, language=None):
         """Parse multiple expressions efficiently."""
         results = []
-        
+
         # Pre-validate language if provided
         if language:
             try:
                 word_groups_for_language(language)
             except InvalidLanguageCodeException:
                 return [{'error': 'Invalid language code'}] * len(expressions)
-        
+
         # Process all expressions
         for expr in expressions:
             try:
                 result = mathparse.parse(expr, language=language)
                 results.append({'success': True, 'result': result})
             except Exception as e:
                 results.append({'success': False, 'error': str(e)})
-        
+
         return results
 
     # Example usage

docs/languages.rst

@@ -15,6 +15,9 @@ The following languages are supported with their ISO 639-2 language codes:
    * - Code
      - Language
      - Example
+   * - CHI
+     - Simplified Chinese
+     - ``'五十 乘 二十 加 十'``
    * - DUT
      - Dutch
      - ``'vijftig maal twintig plus tien'``
@@ -273,6 +276,41 @@ Thai (THA)
     mathparse.parse('สี่ ยกกำลังสอง', language='THA')
     >>> 16
 
+Simplified Chinese (CHI)
+++++++++++++++++++++++++
+
+.. code-block:: python
+
+    # Basic arithmetic using Chinese characters
+    mathparse.parse('五 加 三', language='CHI')
+    >>> 8
+
+    # Multiplication
+    mathparse.parse('六 乘 九', language='CHI')
+    >>> 54
+
+    # Using alternative number representations
+    mathparse.parse('五十 加上 二十', language='CHI')
+    >>> 70
+
+    # Large numbers with scales
+    mathparse.parse('三 百 加 五十', language='CHI')
+    >>> 350
+
+    mathparse.parse('两 千 五 百', language='CHI')
+    >>> 2500
+
+    # Powers and roots
+    mathparse.parse('四 平方', language='CHI')
+    >>> 16
+
+    mathparse.parse('平方根 十六', language='CHI')
+    >>> 4.0
+
+    # Negative numbers
+    mathparse.parse('负 五 加 十', language='CHI')
+    >>> 5
+
 Common Operators by Language
 ----------------------------
 
@@ -298,6 +336,9 @@ English Operators
    * - Division
      - divided by
      - ``'twenty divided by four'``
+   * - Decimal Point
+     - point
+     - ``'five point two'``
    * - Power
      - to the power of
      - ``'two to the power of three'``
@@ -310,6 +351,9 @@ English Operators
    * - Square Root
      - square root of
      - ``'square root of nine'``
+   * - Negative
+     - negative
+     - ``'negative five'``
 
 French Operators
 ++++++++++++++++
@@ -333,6 +377,9 @@ French Operators
    * - Division
      - divisé par
      - ``'vingt divisé par quatre'``
+   * - Decimal Point
+     - virgule
+     - ``'cinq virgule deux'``
    * - Power
      - à la puissance
      - ``'deux à la puissance trois'``

docs/postfix.rst

@@ -115,10 +115,51 @@ The mathparse library converts infix expressions to postfix using the `Shunting-
    result = evaluate_postfix(postfix)       # 11
 
 The conversion process respects operator precedence:
-- Higher precedence: ``^`` (exponentiation), ``*``, ``/`` 
-- Lower precedence: ``+``, ``-``
+- Highest precedence: ``.`` (decimal point)
+- Higher precedence: ``^`` (exponentiation)
+- Medium precedence: ``*``, ``/`` (multiplication, division)
+- Lower precedence: ``+``, ``-`` (addition, subtraction)
 - Parentheses override natural precedence
 
+Decimal Point Operator
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The decimal point (``.``) is treated as a special binary operator with the highest precedence.
+It combines an integer part and a fractional part to create a decimal number.
+
+**How it works:**
+
+.. code-block:: python
+
+   # "53 . 4" is evaluated as: 53 + (4 / 10^1) = 53.4
+   result = mathparse.parse('53 . 4')
+   # Returns: 53.4
+
+   # "10 . 25" is evaluated as: 10 + (25 / 10^2) = 10.25
+   result = mathparse.parse('10 . 25')
+   # Returns: 10.25
+
+**Postfix evaluation:**
+
+.. code-block:: text
+
+   Expression: 53 . 4
+   Postfix: [53, 4, '.']
+
+   Evaluation:
+   Token: 53    Stack: [53]
+   Token: 4     Stack: [53, 4]
+   Token: .     Stack: [53.4]      (combines 53 and 4 into 53.4)
+   Result: 53.4
+
+The decimal operator has the highest precedence to ensure it binds tightly before any other operations:
+
+.. code-block:: python
+
+   # "5 . 2 + 3" is parsed as "(5.2) + 3", not "5 . (2 + 3)"
+   result = mathparse.parse('5 . 2 + 3')
+   # Returns: 8.2
+
 
 Security: Avoiding eval() Vulnerabilities  
 -----------------------------------------