azrideus-mathparse 0.2.9__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
mathparse/mathparse.py ADDED
@@ -0,0 +1,890 @@
1
+ """
2
+ Methods for evaluating mathematical equations in strings.
3
+ """
4
+ from decimal import Decimal
5
+ from typing import Union
6
+ from . import mathwords
7
+ import re
8
+
9
+
10
+ class PostfixTokenEvaluationException(Exception):
11
+ """
12
+ Exception to be raised when an expression cannot be evaluated.
13
+ """
14
+ pass
15
+
16
+
17
+ def is_int(string: str) -> bool:
18
+ """
19
+ Return true if string is an integer.
20
+ """
21
+ # Allow leading minus sign
22
+ if string[0] == '-':
23
+ # Must have at least one digit after the minus
24
+ return len(string) > 1 and string[1:].isdigit()
25
+ else:
26
+ # Must be all digits
27
+ return string.isdigit()
28
+
29
+
30
+ def is_float(string: str) -> bool:
31
+ """
32
+ Return true if the string is a float.
33
+ """
34
+ try:
35
+ float(string)
36
+ return '.' in string
37
+ except ValueError:
38
+ return False
39
+
40
+
41
+ def is_constant(string: str) -> bool:
42
+ """
43
+ Return true if the string is a mathematical constant.
44
+ """
45
+ return mathwords.CONSTANTS.get(string, False)
46
+
47
+
48
+ def is_unary(string: str) -> bool:
49
+ """
50
+ Return true if the string is a defined unary mathematical
51
+ operator function.
52
+ """
53
+ return string in mathwords.UNARY_FUNCTIONS
54
+
55
+
56
+ def is_binary(string: str) -> bool:
57
+ """
58
+ Return true if the string is a defined binary operator.
59
+ """
60
+ return string in mathwords.BINARY_OPERATORS
61
+
62
+
63
+ def is_symbol(string: str) -> bool:
64
+ """
65
+ Return true if the string is a mathematical symbol.
66
+ """
67
+ return (
68
+ is_int(string) or is_float(string) or
69
+ is_constant(string) or is_unary(string) or
70
+ is_binary(string) or
71
+ (string == '(') or (string == ')')
72
+ )
73
+
74
+
75
+ def is_word(word: str, language: str) -> bool:
76
+ """
77
+ Return true if the word is a math word for the specified language.
78
+ """
79
+ words = mathwords.words_for_language(language)
80
+
81
+ return word in words
82
+
83
+
84
+ def to_number(val) -> Union[int, float, str, Decimal]:
85
+ """
86
+ Convert a string to an int or float if possible.
87
+ """
88
+ # If already a number (int, float, Decimal), return as-is
89
+ if isinstance(val, (int, float, Decimal)):
90
+ return val
91
+
92
+ # Check if it's a constant and convert
93
+ if is_constant(val):
94
+ return mathwords.CONSTANTS[val]
95
+
96
+ # Otherwise, try to convert string to number
97
+ if is_int(val):
98
+ return int(val)
99
+ elif is_float(val):
100
+ return float(val)
101
+
102
+ return val
103
+
104
+
105
+ def create_unicode_word_boundary_pattern(word: str) -> str:
106
+ """
107
+ Create a regex pattern with Unicode-aware word boundaries.
108
+
109
+ Standard regex \\b word boundaries don't work with non-ASCII characters
110
+ (e.g., Devanagari, Arabic, Hebrew, Chinese, Thai, etc.). This function
111
+ creates a pattern that works across all Unicode scripts.
112
+
113
+ Args:
114
+ word (str): The word to create a boundary pattern for
115
+
116
+ Returns:
117
+ str: A regex pattern string with proper Unicode boundaries
118
+
119
+ Examples:
120
+ >>> create_unicode_word_boundary_pattern("two")
121
+ '(?<![\\w])two(?![\\w])'
122
+ >>> create_unicode_word_boundary_pattern("दो") # Hindi "two"
123
+ '(?:^|(?<=[\\s+\\-*/^()]))दो(?:$|(?=[\\s+\\-*/^()]))'
124
+ """
125
+ # Check if word contains only ASCII alphanumeric characters
126
+ if word.isascii() and word.replace('-', '').replace("'", '').isalnum():
127
+ # For ASCII words, use standard word boundaries
128
+ return r'\b' + re.escape(word) + r'\b'
129
+ else:
130
+ # For non-ASCII (Unicode) words, use space/operator boundaries
131
+ # This pattern matches the word when it's:
132
+ # - At the start of string OR preceded by whitespace/operator
133
+ # - At the end of string OR followed by whitespace/operator
134
+ escaped_word = re.escape(word)
135
+ # Boundary characters: whitespace, operators, parentheses
136
+ boundary = r'[\s+\-*/^()]'
137
+ return f'(?:^|(?<={boundary})){escaped_word}(?:$|(?={boundary}))'
138
+
139
+
140
+ def find_word_groups(string: str, words: list) -> list:
141
+ """
142
+ Find matches for words in the format "3 thousand 6 hundred 2".
143
+ The words parameter should be the list of words to check for
144
+ such as "hundred".
145
+ """
146
+ scale_pattern = '|'.join(words)
147
+ # For example:
148
+ # (?:(?:\d+)\s+(?:hundred|thousand)*\s*)+(?:\d+|hundred|thousand)+
149
+ regex = re.compile(
150
+ r'(?:(?:\d+)\s+(?:' +
151
+ scale_pattern +
152
+ r')*\s*)+(?:\d+|' +
153
+ scale_pattern + r')+'
154
+ )
155
+ result = regex.findall(string)
156
+ return result
157
+
158
+
159
+ def replace_word_tokens_simplified_chinese(
160
+ string, stopwords: set[str] = None
161
+ ) -> str:
162
+ """
163
+ simplified Chinese version:
164
+ Given a string and an ISO 639-2 language code,
165
+ return the string with the words replaced with
166
+ an operational equivalent.
167
+ """
168
+ words = mathwords.word_groups_for_language('CHI')
169
+
170
+ # Handle special Chinese power construction patterns FIRST
171
+ # In Chinese, '的...次方' forms a power construction where:
172
+ # - '的' acts as a possessive/linking word (provides the ^ operator)
173
+ # - '次方' is a suffix meaning "power" (should be removed, not replaced)
174
+ # - '次幂' is similar to '次方'
175
+ # Example: 二的四次方 = 2's 4th power = 2 ^ 4
176
+ # We need to remove '次方' and '次幂' BEFORE they get replaced as operators
177
+ string = string.replace('次方', ' ')
178
+ string = string.replace('次幂', ' ')
179
+
180
+ # Collect all operators (binary, prefix unary, postfix unary)
181
+ # and process them by length (longest first) to handle cases where
182
+ # a shorter operator is a substring of a longer one
183
+ # Example: '平方' (squared) vs '平方根' (square root)
184
+ all_operators = {}
185
+
186
+ # Add binary operators
187
+ all_operators.update(words['binary_operators'])
188
+
189
+ # Add prefix unary operators
190
+ all_operators.update(words['prefix_unary_operators'])
191
+
192
+ # Add postfix unary operators
193
+ if 'postfix_unary_operators' in words:
194
+ all_operators.update(words['postfix_unary_operators'])
195
+
196
+ # Sort all operators by length (longest first)
197
+ sorted_operators = sorted(all_operators.keys(), key=len, reverse=True)
198
+
199
+ for operator in sorted_operators:
200
+ if operator in string:
201
+ # 中文没有分隔符,后面需要靠分隔符分割式子,每次识别一个符号都将其分开来
202
+ string = string.replace(
203
+ operator, ' ' + all_operators[operator] + ' '
204
+ )
205
+
206
+ # chinese_scales用list的原因是为了保持从大到小的顺序,亿、万、千...
207
+ # Sort scales by their numeric value (largest first) to ensure correct
208
+ # parsing. For example, '千' (1000) should be found before '百' (100)
209
+ digits = set(words['numbers'].keys())
210
+ scales = sorted(
211
+ words['scales'].keys(), key=lambda x: words['scales'][x], reverse=True
212
+ )
213
+ digits_scales = words['numbers'].copy()
214
+ digits_scales.update(words['scales'])
215
+
216
+ # 九千八百万九千八百——> 98009800
217
+ def chinese_string_to_num(str):
218
+ if str == '':
219
+ return 0
220
+
221
+ if str in digits:
222
+ return digits_scales[str]
223
+
224
+ digits_scales.update(words['scales'])
225
+
226
+ for scale in scales:
227
+ index = str.find(scale)
228
+ if index >= 0:
229
+ t1 = chinese_string_to_num(str[:index])
230
+ t2 = digits_scales[scale]
231
+ t3 = chinese_string_to_num(str[index + 1:])
232
+ return t1 * t2 + t3
233
+ else:
234
+ return digits_scales[str]
235
+
236
+ # 扫描看有没有汉字数字,有转化为阿拉伯数字
237
+ index = 0
238
+ start = end = 0
239
+ while True:
240
+ char = string[index]
241
+
242
+ if char in digits_scales:
243
+ end += 1
244
+ index += 1
245
+ else:
246
+ if start < end:
247
+ num = str(chinese_string_to_num(string[start:end]))
248
+ # 需要加多一个分隔符
249
+ num_str = str(num) + ' '
250
+ string = string[:start] + num_str + string[end:]
251
+ index = start + len(num_str)
252
+ start = end = index
253
+ else:
254
+ index += 1
255
+ start = end = index
256
+
257
+ if index >= len(string):
258
+ if start < end:
259
+ num = str(chinese_string_to_num(string[start:end]))
260
+ num_str = str(num) + ' '
261
+ string = string[:start] + num_str + string[end:]
262
+
263
+ break
264
+
265
+ return string
266
+
267
+
268
+ def replace_word_tokens(
269
+ string: str, language: str, stopwords: set[str] = None
270
+ ) -> str:
271
+ """
272
+ Replace word-based mathematical terms with their symbolic equivalents.
273
+
274
+ Given a string and an ISO 639-2 language code,
275
+ return the string with the words replaced with
276
+ an operational equivalent.
277
+
278
+ Args:
279
+ string (str): The input string containing a mathematical expression
280
+ with words.
281
+
282
+ language (str): ISO 639-2 language code for word-based parsing.
283
+
284
+ stopwords (set[str], optional): A set of words to ignore during
285
+ parsing. This can be used to filter out
286
+ non-mathematical words in expressions.
287
+
288
+ Returns:
289
+ str: The input string with word-based mathematical terms replaced
290
+ with their symbolic equivalents.
291
+ """
292
+ words = mathwords.word_groups_for_language(language)
293
+
294
+ # Process operators by length (longest first) to handle compound operators
295
+ binary_operators = words['binary_operators']
296
+ sorted_operators = sorted(binary_operators.keys(), key=len, reverse=True)
297
+ for operator in sorted_operators:
298
+ if operator in string:
299
+ string = string.replace(operator, binary_operators[operator])
300
+
301
+ # Handle prefix unary operators (like "square root of")
302
+ if 'prefix_unary_operators' in words:
303
+ prefix_unary_operators = words['prefix_unary_operators']
304
+ # Sort by length to handle compound operators where a shorter token
305
+ # is a substring of a longer token
306
+ sorted_prefix_operators = sorted(
307
+ prefix_unary_operators.keys(), key=len, reverse=True
308
+ )
309
+ for operator in sorted_prefix_operators:
310
+ if operator in string:
311
+ string = string.replace(
312
+ operator, prefix_unary_operators[operator]
313
+ )
314
+
315
+ # Handle postfix unary operators (like "squared", "cubed")
316
+ if 'postfix_unary_operators' in words:
317
+ postfix_unary_operators = words['postfix_unary_operators']
318
+ # Sort by length to handle compound operators where a shorter token
319
+ # is a substring of a longer token
320
+ sorted_postfix_operators = sorted(
321
+ postfix_unary_operators.keys(), key=len, reverse=True
322
+ )
323
+ for operator in sorted_postfix_operators:
324
+ if operator in string:
325
+ # Captures the number/operand before the unary operator
326
+ pattern = r'(\w+)\s+' + re.escape(operator)
327
+ replacement = r'(\1 ' + postfix_unary_operators[operator] + ')'
328
+ string = re.sub(pattern, replacement, string)
329
+
330
+ # Handle compound numbers:
331
+ # (e.g., "twenty one" -> "(20 + 1)", "fifty four" -> "(50 + 4)")
332
+ numbers = words['numbers']
333
+
334
+ # Create regex patterns for compound numbers
335
+ # Pattern matches: (tens_word) (units_word) where tens_word is
336
+ # 20,30,40,...,90 and units_word is 1-9
337
+ tens_words = {word: value for word, value in numbers.items() if value in [
338
+ 20, 30, 40, 50, 60, 70, 80, 90
339
+ ]}
340
+ units_words = {word: value for word, value in numbers.items() if value in [
341
+ 1, 2, 3, 4, 5, 6, 7, 8, 9
342
+ ]}
343
+
344
+ # Preprocess hyphenated compound numbers
345
+ # (e.g., "fifty-four" -> "fifty four")
346
+ for tens_word in tens_words.keys():
347
+ for units_word in units_words.keys():
348
+ hyphenated_pattern = tens_word + r'-' + units_word
349
+ space_separated = tens_word + ' ' + units_word
350
+ if re.search(hyphenated_pattern, string):
351
+ string = re.sub(hyphenated_pattern, space_separated, string)
352
+
353
+ # Replace compound numbers first (before individual number replacement)
354
+ for tens_word, tens_value in tens_words.items():
355
+ for units_word, units_value in units_words.items():
356
+ compound_pattern = tens_word + r'\s+' + units_word
357
+ compound_replacement = f'({tens_value} + {units_value})'
358
+ if re.search(compound_pattern, string):
359
+ string = re.sub(compound_pattern, compound_replacement, string)
360
+
361
+ # Replace number words with numeric values
362
+ for number in frozenset(numbers.keys()):
363
+ # Use Unicode-aware word boundaries to prevent partial matches
364
+ # (e.g., "nine" in "nineteen") and support non-ASCII scripts
365
+ # (e.g., Devanagari, Arabic, Hebrew, Chinese, etc.)
366
+ pattern = create_unicode_word_boundary_pattern(number)
367
+ if re.search(pattern, string):
368
+ string = re.sub(pattern, str(numbers[number]), string)
369
+
370
+ # Remove words specified to be ignored
371
+ if stopwords:
372
+ filtered_words = []
373
+
374
+ for word in string.split():
375
+ if word not in stopwords:
376
+ filtered_words.append(word)
377
+ string = ' '.join(filtered_words)
378
+
379
+ # Replace scaling multipliers with numeric values
380
+ scales = words['scales']
381
+ end_index_characters = mathwords.BINARY_OPERATORS | {'('}
382
+
383
+ word_matches = find_word_groups(string, frozenset(scales.keys()))
384
+
385
+ for match in word_matches:
386
+ string = string.replace(match, '(' + match + ')')
387
+
388
+ for scale in frozenset(scales.keys()):
389
+ for _ in range(0, string.count(scale)):
390
+ start_index = string.find(scale) - 1
391
+ end_index = len(string)
392
+
393
+ while is_int(string[start_index - 1]) and start_index > 0:
394
+ start_index -= 1
395
+
396
+ end_index = string.find(' ', start_index) + 1
397
+ end_index = string.find(' ', end_index) + 1
398
+
399
+ add = ' + '
400
+ if string[end_index] in end_index_characters:
401
+ add = ''
402
+
403
+ string = string[:start_index] + '(' + string[start_index:]
404
+ string = string.replace(
405
+ scale, '* ' + str(scales[scale]) + ')' + add,
406
+ 1
407
+ )
408
+
409
+ string = string.replace(') (', ') + (')
410
+
411
+ # Remove extra parentheses around all scale expressions to simplify output
412
+ # Convert ((number * scale)) to (number * scale) for all scales
413
+ string = re.sub(r'\(\((\d+\s*\*\s*\d+)\)\)', r'(\1)', string)
414
+
415
+ return string
416
+
417
+
418
+ def preprocess_unary_operators(tokens: list) -> list:
419
+ """
420
+ Preprocess tokens to convert unary minus to the 'neg' function.
421
+
422
+ A minus sign is considered unary (negative) if it appears:
423
+ * At the beginning of the expression
424
+ * After an opening parenthesis '('
425
+ * After a binary operator `(+, -, *, /, ^)`
426
+ * After a unary function `(sqrt, log, neg)`
427
+ """
428
+ if not tokens:
429
+ return tokens
430
+
431
+ processed_tokens = []
432
+
433
+ # A following minus sign should be treated as unary (negative)
434
+ unary_contexts = mathwords.BINARY_OPERATORS | {'('}
435
+
436
+ for i, token in enumerate(tokens):
437
+ if token == '-':
438
+ # Check if this minus should be treated as unary
439
+ is_unary_minus = False
440
+
441
+ if i == 0:
442
+ # The first token is unary minus
443
+ is_unary_minus = True
444
+ elif i > 0:
445
+ prev_token = tokens[i - 1]
446
+ # A unary minus after opening parenthesis, binary operators,
447
+ # or unary functions
448
+ if prev_token in unary_contexts or is_unary(prev_token):
449
+ is_unary_minus = True
450
+
451
+ if is_unary_minus:
452
+ # Convert the unary minus to 'neg' function
453
+ processed_tokens.append('neg')
454
+ else:
455
+ # Keep as binary minus
456
+ processed_tokens.append(token)
457
+ else:
458
+ processed_tokens.append(token)
459
+
460
+ return processed_tokens
461
+
462
+
463
+ def to_postfix(tokens: list) -> list:
464
+ """
465
+ Convert a list of evaluatable tokens to postfix format.
466
+ """
467
+ precedence = {
468
+ '.': 5,
469
+ '^': 4,
470
+ '/': 3,
471
+ '*': 3,
472
+ '+': 2,
473
+ '-': 2,
474
+ '(': 1
475
+ }
476
+
477
+ # Unary functions have a higher precedence than binary operators
478
+ unary_precedence = max(precedence.values()) + 1
479
+
480
+ # Right-associative operators use strict inequality when popping,
481
+ # so that e.g. 2^3^2 evaluates as 2^(3^2) = 512, not (2^3)^2 = 64
482
+ right_associative = {'^'}
483
+
484
+ postfix = []
485
+ opstack = []
486
+
487
+ for token in tokens:
488
+ if is_int(token):
489
+ postfix.append(token)
490
+ elif is_float(token):
491
+ postfix.append(token)
492
+ elif token in mathwords.CONSTANTS:
493
+ postfix.append(token)
494
+ elif is_unary(token):
495
+ opstack.append(token)
496
+ elif token == '(':
497
+ opstack.append(token)
498
+ elif token == ')':
499
+ top_token = opstack.pop()
500
+ while top_token != '(':
501
+ postfix.append(top_token)
502
+ top_token = opstack.pop()
503
+ elif is_binary(token):
504
+ # Pop operators with higher precedence, or equal precedence when
505
+ # the current token is left-associative (right-associative
506
+ # operators like ^ only yield to strictly higher precedence so
507
+ # that 2^3^2 = 2^(3^2) = 512 rather than (2^3)^2 = 64).
508
+ is_left_assoc = token not in right_associative
509
+ while (opstack != []) and (
510
+ (
511
+ opstack[-1] in precedence and token in precedence and (
512
+ precedence[opstack[-1]] > precedence[token] or (
513
+ is_left_assoc and
514
+ precedence[opstack[-1]] == precedence[token]
515
+ )
516
+ )
517
+ ) or
518
+ (
519
+ is_unary(
520
+ opstack[-1]
521
+ ) and unary_precedence >= precedence[token]
522
+ )
523
+ ):
524
+ postfix.append(opstack.pop())
525
+ opstack.append(token)
526
+ else:
527
+ # Raise exception for unsupported mathematical terms
528
+ raise PostfixTokenEvaluationException(
529
+ 'Unsupported mathematical term: "{}"'.format(token)
530
+ )
531
+
532
+ while opstack != []:
533
+ postfix.append(opstack.pop())
534
+
535
+ return postfix
536
+
537
+
538
+ def evaluate_postfix(tokens: list) -> Union[int, float, str, Decimal]:
539
+ """
540
+ Given a list of evaluatable tokens in postfix format,
541
+ calculate a solution.
542
+ """
543
+ stack = []
544
+
545
+ for token in tokens:
546
+ total = None
547
+
548
+ if is_int(token) or is_float(token) or is_constant(token):
549
+ stack.append(token)
550
+ elif is_unary(token):
551
+ a = stack.pop()
552
+ # Convert token (string) to number for unary function evaluation
553
+ a = to_number(a)
554
+ total = mathwords.UNARY_FUNCTIONS[token](a)
555
+ elif len(stack) == 1:
556
+ raise PostfixTokenEvaluationException(
557
+ 'Insufficient values in expression for operator "{}"'.format(
558
+ token
559
+ )
560
+ )
561
+ elif len(stack) > 1:
562
+ b = stack.pop()
563
+ a = stack.pop()
564
+
565
+ if token == '+':
566
+ total = to_number(a) + to_number(b)
567
+ elif token == '-':
568
+ total = to_number(a) - to_number(b)
569
+ elif token == '*':
570
+ total = to_number(a) * to_number(b)
571
+ elif token == '^':
572
+ total = to_number(a) ** to_number(b)
573
+ elif token == '/':
574
+ if Decimal(str(b)) == 0:
575
+ total = 'undefined'
576
+ else:
577
+ total = Decimal(str(a)) / Decimal(str(b))
578
+ elif token == '.':
579
+ # Treat decimal points as a binary operator that combines the
580
+ # integer and fractional part of two numbers
581
+ # Example: 53 . 25 = 53.25, -3 . 5 = -3.5
582
+
583
+ # Convert b to number
584
+ numeric_b = to_number(b)
585
+
586
+ if numeric_b == 0:
587
+ # Convert a to number
588
+ numeric_a = to_number(a)
589
+ total = Decimal(numeric_a)
590
+ else:
591
+ # Check if 'a' has a negative sign (handles -0 case)
592
+ is_negative = str(a).startswith('-')
593
+
594
+ # Convert a to number for calculation
595
+ numeric_a = to_number(a)
596
+
597
+ # Count the digits in the original string b to preserve
598
+ # leading zeros (e.g., "01" has 2 digits, not 1)
599
+ digits = len(str(b))
600
+ divisor = 10 ** digits
601
+ fractional_part = numeric_b / divisor
602
+
603
+ # Handle negatives: -3 . 5 = -3.5, not -2.5
604
+ # Also -0 . 5 = -0.5 (check string since -0 == 0)
605
+ if is_negative:
606
+ total = numeric_a - fractional_part
607
+ else:
608
+ total = numeric_a + fractional_part
609
+ else:
610
+ raise PostfixTokenEvaluationException(
611
+ 'Unknown token "{}"'.format(token)
612
+ )
613
+
614
+ if total is not None:
615
+ stack.append(total)
616
+
617
+ # If the stack is empty the tokens could not be evaluated
618
+ if not stack:
619
+ raise PostfixTokenEvaluationException(
620
+ 'The postfix expression resulted in an empty stack'
621
+ )
622
+
623
+ result = stack.pop()
624
+
625
+ # Convert final result from string to number if needed
626
+ if isinstance(result, str):
627
+ if is_int(result):
628
+ result = int(result)
629
+ elif is_float(result):
630
+ result = float(result)
631
+
632
+ return result
633
+
634
+
635
+ def tokenize(string: str, language: str = None, escape: str = '___') -> list:
636
+ """
637
+ Convert a string into a list of mathematical tokens for processing.
638
+
639
+ Args:
640
+ string (str): The input string containing a mathematical expression.
641
+
642
+ language (str, optional): ISO 639-2 language code for word-based
643
+ parsing. If None, only numeric expressions
644
+ are supported.
645
+
646
+ escape (str, optional): A string used to temporarily replace spaces
647
+ in multi-word phrases during tokenization.
648
+ Default is '___'.
649
+
650
+ Returns:
651
+ list: A list of tokens extracted from the input string.
652
+ """
653
+ # Set all words to lowercase
654
+ string = string.lower()
655
+
656
+ # Ignore punctuation
657
+ if len(string) and not string[-1].isalnum():
658
+ character = string[-1]
659
+ string = string[:-1] + ' ' + character
660
+
661
+ # If language is specified, normalize compound operators by removing
662
+ # spaces between their characters. This handles cases like '乘 以'
663
+ # which should be treated as the single compound operator '乘以'.
664
+ # Process by length (longest first) to avoid partial matches.
665
+ if language:
666
+ words = mathwords.words_for_language(language)
667
+
668
+ # Sort all phrases by length (longest first) to handle cases where
669
+ # a shorter phrase is a substring of a longer one
670
+ phrases_by_length = sorted(words, key=len, reverse=True)
671
+
672
+ for phrase in phrases_by_length:
673
+ # For multi-character phrases, create a spaced version
674
+ # and replace it with the non-spaced version
675
+ if len(phrase) > 1:
676
+ # Create pattern with optional spaces between each character
677
+ # For example, '乘以' could appear as '乘 以' or '乘 以'
678
+ spaced_phrase = ' '.join(phrase)
679
+ # Replace spaced version with non-spaced version
680
+ string = string.replace(spaced_phrase, phrase)
681
+
682
+ # Binary operators must have space around them to be tokenized properly
683
+ # Special handling for minus sign: preserve leading negatives
684
+ for operator in mathwords.BINARY_OPERATORS:
685
+ if operator == '-':
686
+ # For minus sign, use a pattern that only spaces it when it's
687
+ # clearly a binary operator (after digits or closing parenthesis).
688
+ # This preserves leading negatives like "-3" and distinguishes
689
+ # between:
690
+ # - "What is -3 + 3" --> "-3 + 3" (minus is part of number)
691
+ # - "5 - 3" --> "5 - 3" (minus is binary operator, needs spacing)
692
+ # - "math - 4" --> "- 4" (minus after letters is not a binary
693
+ # operator)
694
+ # Only add spaces around minus when preceded by a digit or closing
695
+ # parenthesis
696
+ string = re.sub(r'([\d)])\s*-\s*', r'\1 - ', string)
697
+ else:
698
+ string = string.replace(operator, f' {operator} ')
699
+
700
+ # Parenthesis must have space around them to be tokenized properly
701
+ string = string.replace('(', ' ( ')
702
+ string = string.replace(')', ' ) ')
703
+
704
+ if language:
705
+ words = mathwords.words_for_language(language)
706
+
707
+ for phrase in words:
708
+ escaped_phrase = phrase.replace(' ', escape)
709
+ string = string.replace(phrase, escaped_phrase)
710
+
711
+ tokens = string.split()
712
+
713
+ for index, token in enumerate(tokens):
714
+ tokens[index] = token.replace(escape, ' ')
715
+
716
+ return tokens
717
+
718
+
719
+ def parse(
720
+ string: str, language: str = None, stopwords: set[str] = None
721
+ ) -> Union[int, float, str, Decimal]:
722
+ """
723
+ Parse and evaluate a mathematical expression from a string.
724
+
725
+ This is the main entry point for mathparse. It can handle both numeric
726
+ expressions (like "2 + 3 * 4") and word-based expressions in various
727
+ languages (like "five plus three" in English).
728
+
729
+ Args:
730
+ string (str): The mathematical expression to parse and evaluate.
731
+ Can contain numbers, operators, parentheses, constants,
732
+ and functions. For word-based parsing, must use terms
733
+ from the specified language.
734
+ language (str, optional): ISO 639-2 language code for word-based
735
+ parsing. Supported codes: 'ENG', 'FRE', 'GER',
736
+ 'GRE', 'ITA', 'MAR', 'RUS', 'POR'. If None,
737
+ only numeric expressions are supported.
738
+ stopwords (set[str], optional): A set of words to ignore during
739
+ parsing. This can be used to filter out
740
+ non-mathematical words in expressions.
741
+
742
+ Returns:
743
+ int, float, or str: The result of the mathematical expression.
744
+ Returns 'undefined' for division by zero.
745
+ For division operations, returns a Decimal object
746
+ to maintain precision.
747
+
748
+ Raises:
749
+ InvalidLanguageCodeException:
750
+ An unsupported language code was provided.
751
+ PostfixTokenEvaluationException:
752
+ The expression cannot be evaluated.
753
+
754
+ Examples:
755
+ >>> parse('2 + 3 * 4')
756
+ 14
757
+
758
+ >>> parse('five plus three', language='ENG')
759
+ 8
760
+
761
+ >>> parse('(seven * nine) + 8 - (45 plus two)', language='ENG')
762
+ 24
763
+
764
+ >>> parse('sqrt 16')
765
+ 4.0
766
+
767
+ >>> parse('pi * 2')
768
+ 6.283386
769
+
770
+ >>> parse('10 / 0')
771
+ 'undefined'
772
+
773
+ Note:
774
+ - Follows standard order of operations (PEMDAS)
775
+ - Supports mathematical constants: pi, e
776
+ - Supports unary functions: sqrt, log
777
+ - Each expression must use terms from a single language
778
+ - Division by zero returns 'undefined' instead of raising an exception
779
+ """
780
+ if language:
781
+ if language == 'CHI':
782
+ string = replace_word_tokens_simplified_chinese(
783
+ string, stopwords
784
+ )
785
+ else:
786
+ string = replace_word_tokens(string, language, stopwords)
787
+
788
+ tokens = tokenize(string, language)
789
+ tokens = preprocess_unary_operators(tokens)
790
+ postfix = to_postfix(tokens)
791
+
792
+ return evaluate_postfix(postfix)
793
+
794
+
795
+ def extract_expression(dirty_string: str, language: str) -> str:
796
+ """
797
+ Extract a mathematical expression from a sentence containing extra text.
798
+
799
+ This function identifies and extracts the mathematical portion from
800
+ natural language sentences like:
801
+ "What is 4 + 4?" or "Calculate five plus three".
802
+ It works by finding the longest sequence of mathematical symbols and words.
803
+
804
+ Args:
805
+ dirty_string (str): A sentence or phrase containing a mathematical
806
+ expression mixed with other text.
807
+ language (str): ISO 639-2 language code to identify mathematical
808
+ words in the target language.
809
+
810
+ Returns:
811
+ str: The extracted mathematical expression as a string.
812
+
813
+ Examples:
814
+ >>> extract_expression("What is 5 plus 3?", language='ENG')
815
+ '5 plus 3'
816
+
817
+ >>> extract_expression(
818
+ "Please calculate two times seven", language='ENG'
819
+ )
820
+ 'two times seven'
821
+
822
+ >>> extract_expression(
823
+ "The result of 10 / 2 should be 5", language=None
824
+ )
825
+ '10 / 2'
826
+
827
+ Note:
828
+ - The function looks for continuous sequences of mathematical terms
829
+ - Non-mathematical words at the beginning and end are stripped
830
+ - The language parameter is required to identify word-based math terms
831
+ """
832
+ tokens = tokenize(dirty_string, language)
833
+
834
+ start_index = 0
835
+ end_index = len(tokens)
836
+
837
+ # Find the start of the mathematical expression
838
+ # Skip over non-mathematical tokens AND isolated binary operators
839
+ for i, part in enumerate(tokens):
840
+ if is_symbol(part) or is_word(part, language):
841
+ # A potential start was found, so check if it's a standalone binary
842
+ # operator. Binary operators (except '(') are only valid at the
843
+ # start if they are unary (such as a leading minus for a negative
844
+ # number)
845
+ if part in mathwords.BINARY_OPERATORS and part != '(':
846
+ # For a binary operator to be the start of an expression, it
847
+ # must be:
848
+ # 1. At the very beginning (position 0) - could be unary minus
849
+ # 2. OR all previous tokens were non-mathematical - also could
850
+ # be unary
851
+ # If there were non-math tokens before it, it's likely a
852
+ # separator
853
+
854
+ # Check if all previous tokens are non-mathematical
855
+ all_prev_non_math = True
856
+ for j in range(i):
857
+ if is_symbol(tokens[j]) or is_word(tokens[j], language):
858
+ all_prev_non_math = False
859
+ break
860
+
861
+ # Only include this operator if at start OR all previous
862
+ # non-math AND followed by a mathematical token
863
+ if all_prev_non_math and i + 1 < len(tokens):
864
+ next_token = tokens[i + 1]
865
+ if (
866
+ is_int(next_token) or is_float(next_token) or
867
+ is_constant(next_token) or is_unary(next_token) or
868
+ next_token == '(' or is_word(next_token, language)
869
+ ):
870
+ start_index = i
871
+ break
872
+ else:
873
+ # Start indexes can be an opening parenthesis, or a non-binary
874
+ # operator
875
+ start_index = i
876
+ break
877
+
878
+ for part in reversed(tokens):
879
+ if is_symbol(part) or is_word(part, language):
880
+ break
881
+ else:
882
+ end_index -= 1
883
+
884
+ result = ' '.join(tokens[start_index:end_index])
885
+
886
+ # Remove spaces around decimal points for cleaner output
887
+ # Replace " . " with "." to convert "-100 . 5" to "-100.5"
888
+ result = result.replace(' . ', '.')
889
+
890
+ return result