help/unexpected

   1 Unexpected
   2
   3     While calc is C-like, users of C will find some unexpected
   4     surprises in calc syntax and usage.  Persons familiar with C should
   5     review this file.
   6
   7
   8     The Comma
   9     =========
  10
  11     The comma is also used for continuation of obj and mat creation
  12     expressions and for separation of expressions to be used for
  13     arguments or values in function calls or initialization lists.  The
  14     precedence order of these different uses is:  continuation,
  15     separator, comma operator.  For example, assuming the variables a,
  16     b, c, d, e, and object type xx have been defined, the arguments
  17     passed to f in:
  18
  19             f(a, b, c, obj xx d, e)
  20
  21     are a, b, c, and e, with e having the value of a newly created xx
  22     object.  In:
  23
  24             f((a, b), c, (obj xx d), e)
  25
  26     the arguments of f are b, c, d, e, with only d being a newly
  27     created xx object.
  28
  29     In combination with other operators, the continuation use of the
  30     comma has the same precedence as [] and ., the separator use the
  31     same as the comma operator.  For example, assuming xx.mul() has
  32     been defined:
  33
  34             f(a = b, obj xx c, d = {1,2} * obj xx e = {3,4})
  35
  36     passes two arguments: a (with value b) and the product d * e of two
  37     initialized xx objects.
  38
  39
  40     ^ is not xor
  41     ============
  42
  43     In C, ^ is the xor operator.  Like the '**', '^' is the
  44     exponentiation operator.  The expression:
  45
  46             a^b
  47
  48     yields "a to the b power", NOT "a xor b".
  49
  50     Note that 'b' must be an integer.  Also if 'a' == 0, 'b'
  51     must be >= 0 as well.
  52
  53     To raise to a non-integer power, use the power() builtin function.
  54
  55
  56     ** is exponentiation
  57     ====================
  58
  59     As was suggested in the '^ is not xor' section, the expression:
  60
  61             a**b
  62
  63     yields "a to the b power", NOT "a xor b".
  64
  65     Note that 'b' must be an integer.  Also if 'a' == 0, 'b'
  66     must be >= 0 as well.
  67
  68     To raise to a non-integer power, use the power() builtin function.
  69
  70
  71     op= operators associate left to right
  72     =====================================
  73
  74     Operator-with-assignments:
  75
  76             +=  -=  *=  /=  %=  //=  &=  |=  <<=  >>=  ^=  **=
  77
  78     associate from left to right instead of right to left as in C.
  79     For example:
  80
  81             a += b *= c
  82
  83     has the effect of:
  84
  85             a = (a + b) * c
  86
  87     where only 'a' is required to be an lvalue.  For the effect of:
  88
  89             b *= c; a += b
  90
  91     when both 'a' and 'b' are lvalues, use:
  92
  93             a += (b *= c)
  94
  95
  96     || yields values other than 0 or 1
  97     ==================================
  98
  99     In C:
 100
 101             a || b
 102
 103     will produce 0 or 1 depending on the logical evaluation
 104     of the expression.  In calc, this expression will produce
 105     either 'a' or 'b' and is equivalent to the expression:
 106
 107             a ? a : b
 108
 109     In other words, if 'a' is true, then 'a' is returned, otherwise
 110     'b' is returned.
 111
 112
 113     && yields values other than 0 or 1
 114     ==================================
 115
 116     In C:
 117
 118             a && b
 119
 120     will produce 0 or 1 depending on the logical evaluation
 121     of the expression.  In calc, this expression will produce
 122     either 'a' or 'b' and is equivalent to the expression:
 123
 124             a ? b : a
 125
 126     In other words, if 'a' is true, then 'b' is returned, otherwise
 127     'a' is returned.
 128
 129
 130     / is fractional divide, // is integral divide
 131     =============================================
 132
 133     In C:
 134
 135             x/y
 136
 137     performs integer division when 'x' and 'y' are integer types.
 138     In calc, this expression yields a rational number.
 139
 140     Calc uses:
 141
 142             x//y
 143
 144     to perform division with integer truncation and is the equivalent to:
 145
 146             int(x/y)
 147
 148
 149     | and & have higher precedence than ==, +, -, *, / and %
 150     ========================================================
 151
 152     Is C:
 153
 154             a == b | c * d
 155
 156     is interpreted as:
 157
 158             (a == b) | (c * d)
 159
 160     and calc it is interpreted as:
 161
 162             a == ((b | c) * d)
 163
 164
 165     calc always evaluates terms from left to right
 166     ==============================================
 167
 168     Calc has a definite order for evaluation of terms (addends in a
 169     sum, factors in a product, arguments for a function or a matrix,
 170     etc.).  This order is always from left to right. but skipping of
 171     terms may occur for ||, && and ? : .
 172
 173     Consider, for example:
 174
 175             A * B + C * D
 176
 177     In calc above expression is evaluated in the following order:
 178
 179             A
 180             B
 181             A * B
 182             C
 183             D
 184             C * D
 185             A * B + C * D
 186
 187     This order of evaluation is significant if evaluation of a
 188     term changes a variable on which a later term depends.  For example:
 189
 190             x++ * x++ + x++ * x++
 191
 192     in calc returns the value:
 193
 194             x * (x + 1) + (x + 2) * (x + 3)
 195
 196     and increments x as if by x += 4.  Similarly, for functions f, g,
 197     the expression:
 198
 199             f(x++, x++) + g(x++)
 200
 201     evaluates to:
 202
 203             f(x, x + 1) + g(x + 2)
 204
 205     and increments x three times.
 206
 207
 208     &A[0] and A are different things in calc
 209     ========================================
 210
 211     In calc, value of &A[0] is the address of the first element, whereas
 212     A is the entire array.
 213
 214
 215     *X may be used to to return the value of X
 216     ==========================================
 217
 218     If the current value of a variable X is an octet, number or string,
 219     *X may be used to to return the value of X; in effect X is an
 220     address and *X is the value at X.
 221
 222
 223     freeing a variable has the effect of assigning the null value to it
 224     ===================================================================
 225
 226     The freeglobals(), freestatics(), freeredc() and free() free
 227     builtins to not "undefine" the variables, but have the effect of
 228     assigning the null value to them, and so frees the memory used for
 229     elements of a list, matrix or object.
 230
 231     Along the same lines:
 232
 233             undefine *
 234
 235     undefines all current user-defined functions.  After executing
 236     all the above freeing functions (and if necessary free(.) to free
 237     the current "old value"), the only remaining numbers as displayed by
 238
 239             show numbers
 240
 241     should be those associated with epsilon(), and if it has been
 242     called, qpi().
 243
 244
 245     #! is also a comment
 246     ====================
 247
 248     In addition to the C style /* comment lines */, lines that begin with
 249     #! are treated as comments.
 250