push_parse_text Function (ROM Call 0x3CA)

AMS 1.01 or higher estack.h

short push_parse_text (const char *str);

Parses an expression given in a string and pushes tokenized expression to the expression stack.

push_parse_text is an extremely powerful function: it parses the expression given in the string str, and pushes the expressions (in RPN form) to the expression stack. This function also can parse TI-Basic statements (after parsing, the tokenized form of these statements is pushed on the expression stack too). push_parse_text returns FALSE if the expression is a multi expression (i.e. if it contains ":" [separator], "->" [store] or TI-Basic statements), otherwise it returns TRUE. This routine may cause expansion of the expression stack or heap compression. TIGCCLIB internally uses this function (together with estack_number_to_Float) in the implementation of atof function. For more examples of usage of this function, see NG_approxESI, NG_rationalESI, NG_execute etc. The "inverse" function of push_parse_text is display_statements.

If you want to perform highly advanced symbolic operations with expressions, you should know that expressions created by push_parse_text are not always organized on a way which allows the most efficient symbolic processing (so-called internal canonic form). For example, TIOS always converts 'x*3' into '3*x' and converts 'x-y' into 'x+y*(-1)', although it will be printed as 'x-y'. However, expressions created by push_parse_text are always as-is, i.e. '3*x' will be just '3*x', not 'x*3'. Some routines (like numeric_factor_index for example) may be fooled if the expression is not "sorted" correctly. Also, some routines (like lead_term_index, lead_factor_index etc.) may also be fooled with expressions like 'x-y' and 'x/y', because operators '-' and '/' are usually never seen in expressions during symbolic processing (the processing is more unique if addition and subtraction are treated as the same operation; the same is true for '*' and '/'). So, if you planed to perform some advanced symbolic processing which is based on accessing various part of the expression, always call push_internal_simplify after calling push_parse_text. This function pushes on the expression stack the same expression but converted in internal canonic form.

Note: push_parse_text will throw an error if the string contains expression with wrong syntax, so you need to use TRY etc. to catch eventual errors. And, the string must be built using TI-Basic conventions (for example, you must use 0xAD ("small" minus) instead of '-' for unary minus, etc. See NG_tokenize for a more powerful function which doesn't throw any errors, and which can determine the exact location and type of the error.


Uses: are_expressions_identical, check_estack_size, delete_between, delete_expression, is_valid_smap_aggregate, map_tail, move_between_to_top, next_expression_index, push_between, push_expression, push_Float, push_quantum, push_quantum_pair, push_reversed_tail, top_estack, ER_catch, ER_success, ER_throwVar, OSCheckBreak, CTypeTable, fix_loop_displacements, is_pathname, next_token, nonblank, primary_tag_list, push_ans_entry, push_var, CheckReservedName, DerefSym, FindSymInFolder, TempFolderName, ROM Call 0x4D4, ROM Call 0x5C5, ROM Call 0x5EF, ROM Call 0x5F0
Used by: NG_tokenize, TokenizeSymName, push_str_to_expr, handleVarLinkKey, HomeExecute, atof, FolderDel, FolderRename, HSymDel, SymFindFolderName, ROM Call 0x46F, ROM Call 0x5F1