CCalc documentation and reference


Homepage | Download | Reference


Contents

CCalc formulas syntax

      You may use mathematically-correct formulas, including brackets, functions etc.

CCalc formulas syntax admits:

Correct formulas examples

(sin(Pi/2) + 1) / 4
= 0.5
2 > 3
= 0 (false)
(2*2=4) ? 1 : 0
= 1
round( 1.2345, 2 )
= 1.23
round( 27.45, -1 )
= 30

Notes

$ operation.
A $ B - integerly divide A by B; if there was a remainder, the result is increased by 1. Usage example: for production B (or less) units of wares we spend one unit of resource ("discrete" resource). It is necessary to know how much resource units we need for producting A units of warez.

CCalc script

CCalc script begins with "#!". The syntax is clear from the example:

#!
a := 2;
b := 3;
return a * b + 1;

CCalc Library

There library consists of three components with their own API:

StrMap (strmap.h)
Small "sublibrary" for working with "string lists". You must communicate with StrMap if you want to add your own user-defined functions (UDFs) and user-defined variables (UDVs)
Lexer (lexer.h)
Universal lexical analyser used as backend layer for parsing expressions. In general developers have no need to communicate directly with Lexer. But they can use it separately for their own needs.
MathParser (mparser.h)
Core component which calculates expressions. It is very easy to use but may be hard to initialize to match your needs.

StrMap reference

hqStrMap* Strmap_Create( int extrabytes, int dup );
hqStrMap* Strmap_CreateFromChain( int extrabytes, char *strchain, void *data );
void StrMap_Destroy( hqStrMap* strmap );

void StrMap_AddString( hqStrMap* strmap, char *str, void *data );
void StrMap_AddStrLen( hqStrMap* strmap, char *str, int len, void *data );
void StrMap_ShrinkMem( hqStrMap* strmap );
void StrMap_Trim( hqStrMap* strmap, int NewCount );
void StrMap_TrimClear( hqStrMap* strmap, int NewCount );
void StrMap_SetCapacity( hqStrMap* strmap, int NewCapacity );
int StrMap_IndexOf( hqStrMap* strmap, char *str, void **data );
int StrMap_LenIndexOf( hqStrMap* strmap, char *str, int len, void **data );
char* StrMap_GetString( hqStrMap* strmap, int index, int *len, void **data );
void Strmap_FillFromChain( hqStrMap* strmap, char *strchain, void *data );

I have no time to describe each function, just some examples of most common usage:

Creating list of variables from "char chain"

Variables will be associated with double values;

char varnames[] = "X\000" "Y\000" "Z\000\000";
double varvalues[] = { 5.3, 6.1, -7.45 };

hqStrMap* varmap = Strmap_CreateFromChain( sizeof(double), varnames, varvalues );

...

StrMap_Destroy( varmap );
Note that varnames is a special data structure ("char chain"):
a string containing zero-separated "substrings" terminated by double zero.

Creating list of variables step-by-step


double varvalues[] = { 5.3, 6.1 };

hqStrMap* varmap = Strmap_Create( sizeof(double), 0 /* do not copy strings */ ); 

StrMap_AddString( varmap, "X", varvalues );
StrMap_AddString( varmap, "Y", varvalues+1 );

...

StrMap_Destroy( varmap );

MathParser reference

typedef struct {
    /* public */
    hqStrMap   *Parameters;
    hqStrMap   *ExtFunctions;
    PrmSrchFunc MoreParams;
    void       *ParamFuncParam;
    /* private */
    ...
} hqMathParser;

hqMathParser* MathParser_Create( char *MoreLetters );
void MathParser_Destroy( hqMathParser* parser );
char* MathParser_Parse( hqMathParser* parser, char *Formula, double *result );
Some examples of usage:

Initializing MathParser for using with list of UDVs

hqMathParser* parser = MathParser_Create( NULL );

/* ... creating list of variables. See StrMap reference for example */

parser->Parameters = varmap;

/* ... parsing expressions */

MathParser_Destroy( parser );

Calculating expression

double result;
char *ErrMsg = MathParser_Parse( parser, "sin(x * x) / 2", &result );
if ( ErrMsg == NULL )
    printf( "%.15G\n", result );
else {
    puts( ErrMsg );


Of course this documentation is incomplete as I have no time now to write more. For more information see ccalc.c as an example of usage of the library;