libSBML C++ API  5.11.0
FormulaTokenizer.h File Reference

Tokenizes an SBML formula string. More...

Include dependency graph for FormulaTokenizer.h:
This graph shows which files directly or indirectly include this file:

Classes

struct  FormulaTokenizer_t
  Tracks the state of tokenizing a formula string. More...
 
struct  Token_t
  A token from FormulaTokenizer_nextToken(). More...
 

Enumerations

enum  TokenType_t {
  TT_PLUS = '+',
  TT_MINUS = '-',
  TT_TIMES = '*',
  TT_DIVIDE = '/',
  TT_POWER = '^',
  TT_LPAREN = '(',
  TT_RPAREN = ')',
  TT_COMMA = ',',
  TT_END = '\0',
  TT_NAME = 256,
  TT_INTEGER,
  TT_REAL,
  TT_REAL_E,
  TT_UNKNOWN
}
 Enumeration of possible token types. More...
 

Functions

FormulaTokenizer_tFormulaTokenizer_createFromFormula (const char *formula)
 Creates a new FormulaTokenizer_t structure for the given formula string and returns a pointer to the structure. More...
 
void FormulaTokenizer_free (FormulaTokenizer_t *ft)
 Frees the given FormulaTokenizer_t structure ft. More...
 
Token_tFormulaTokenizer_nextToken (FormulaTokenizer_t *ft)
 Returns the next token in the formula string. More...
 

Detailed Description

Tokenizes an SBML formula string.

Author
Ben Bornstein

This file contains functions to tokenize a text string containing a mathematical formula in SBML Level 1 syntax. The first entry point is the function FormulaTokenizer_createFromFormula(), which returns a FormulaTokenizer_t structure. The structure tracks the current position in the string to be tokenized, and can be handed to other functions such as FormulaTokenizer_nextToken(). Tokens are returned as Token_t structures.

The Token_t structure

The Token_t structure is used to store a token returned by FormulaTokenizer_nextToken(). It contains a union whose members can store different types of tokens, such as numbers and symbols.

The FormulaTokenizer_t structure

An instance of a FormulaTokenizer_t maintains its own internal copy of the formula being tokenized and the current position within the formula string. Callers do not need to manipulate the fields of a FormulaTokenizer_t structure themselves; instances of FormulaTokenizer_t are only meant to be passed around between the functions of the formula tokenizer system, such as FormulaTokenizer_createFromFormula() and FormulaTokenizer_getName().

Note
Callers using SBML Level 3 are encouraged to use the facilities provided by libSBML's newer and more powerful Level 3-oriented formula parser and formatter. The entry points to this second system are SBML_parseL3Formula() and SBML_formulaToL3String(). The Level 1-oriented system (i.e., what is provided by SBML_formulaToString() and SBML_parseFormula()) is provided untouched for backwards compatibility.
We urge developers to keep in mind that the text-string formula syntax is specific to libSBML. Neither MathML nor SBML define a text-string format for mathematical formulas. LibSBML's particular syntax should not be considered to be a canonical or standard general-purpose mathematical expression syntax. LibSBML provides methods for parsing and transforming text-string math formulas back and forth from AST structures for the convenience of calling applications, but it is important to keep the system's limitations in mind.

Enumeration Type Documentation

Enumeration of possible token types.

"TT" is short for "TokenType".

See also
Token_t
Enumerator
TT_PLUS 

The '+' token

TT_MINUS 

The '-' token

TT_TIMES 

The '*' token

TT_DIVIDE 

The '/' token

TT_POWER 

The '^' token

TT_LPAREN 

The '(' token

TT_RPAREN 

The ')' token

TT_COMMA 

The ',' token

TT_END 

The end-of-input token

TT_NAME 

The token for a name

TT_INTEGER 

The token for an integer

TT_REAL 

The token for a real number (number with a decimal point)

TT_REAL_E 

The token for a real number using e-notation

TT_UNKNOWN 

An unknown token

Function Documentation

FormulaTokenizer_t* FormulaTokenizer_createFromFormula ( const char *  formula)

Creates a new FormulaTokenizer_t structure for the given formula string and returns a pointer to the structure.

SBML Level 1 uses a simple text-string representation of mathematical formulas, rather than the MathML-based representation used in SBML Levels 2 and 3. LibSBML implements a parser and converter to translate formulas between this text-string representation and MathML. The first entry point is the function FormulaTokenizer_createFromFormula(), which returns a FormulaTokenizer_t structure. The structure tracks the current position in the string to be tokenized, and can be handed to other functions such as FormulaTokenizer_nextToken(). Tokens are returned as Token_t structures.

Parameters
formulathe text string that contains the mathematical formula to be tokenized.
Returns
a FormulaTokenizer_t structure that tracks the state of tokenizing the string.
See also
FormulaTokenizer_nextToken()
FormulaTokenizer_free()
Note
We urge developers to keep in mind that the text-string formula syntax is specific to libSBML. Neither MathML nor SBML define a text-string format for mathematical formulas. LibSBML's particular syntax should not be considered to be a canonical or standard general-purpose mathematical expression syntax. LibSBML provides methods for parsing and transforming text-string math formulas back and forth from AST structures for the convenience of calling applications, but it is important to keep the system's limitations in mind.
void FormulaTokenizer_free ( FormulaTokenizer_t ft)

Frees the given FormulaTokenizer_t structure ft.

Token_t* FormulaTokenizer_nextToken ( FormulaTokenizer_t ft)

Returns the next token in the formula string.

SBML Level 1 uses a simple text-string representation of mathematical formulas, rather than the MathML-based representation used in SBML Levels 2 and 3. LibSBML implements a parser and converter to translate formulas between this text-string representation and MathML. The first entry point is the function FormulaTokenizer_createFromFormula(), which returns a FormulaTokenizer_t structure. The structure tracks the current position in the string to be tokenized, and can be handed to other functions such as FormulaTokenizer_nextToken(). Tokens are returned as Token_t structures.

An instance of a FormulaTokenizer_t maintains its own internal copy of the formula being tokenized and the current position within the formula string. Callers do not need to manipulate the fields of a FormulaTokenizer_t structure themselves; instances of FormulaTokenizer_t are only meant to be passed around between the functions of the formula tokenizer system, such as FormulaTokenizer_createFromFormula() and FormulaTokenizer_getName().

Parameters
ftthe structure tracking the current tokenization state.
Returns
a pointer to a token. If no more tokens are available, the token type will be TT_END. Please consult the documentation for the structure Token_t for more information about the possible data values it can hold.
See also
FormulaTokenizer_free()
FormulaTokenizer_createFromFormula()
Note
We urge developers to keep in mind that the text-string formula syntax is specific to libSBML. Neither MathML nor SBML define a text-string format for mathematical formulas. LibSBML's particular syntax should not be considered to be a canonical or standard general-purpose mathematical expression syntax. LibSBML provides methods for parsing and transforming text-string math formulas back and forth from AST structures for the convenience of calling applications, but it is important to keep the system's limitations in mind.