help/STATEMENT

   1 Statements
   2
   3     Statements are very much like C statements.  Most statements act
   4     identically to those in C, but there are minor differences and
   5     some additions.  The following is a list of the statement types,
   6     with explanation of the non-C statements.  In this list, upper
   7     case words identify the keywords which are actually in lower case.
   8     Statements are generally terminated with semicolons, except if the
   9     statement is the compound one formed by matching braces.  Various
  10     expressions are optional and may be omitted (as in RETURN).
  11
  12
  13     C-like statements
  14     -----------------
  15     { statement }
  16     { statement; ... statement }
  17     if (expr) statement
  18     if (expr) statement ELSE statement
  19     for (optionalexpr ; optionalexpr ; optionalexpr) statement
  20     while (expr) statement
  21     do statement while (expr)
  22     continue
  23     break
  24     goto label
  25             These all work like in normal C.
  26
  27             See 'help expression' for details on expressions.
  28             See 'help builtin' for details on calc builtin functions.
  29
  30
  31     return
  32     ------
  33     return optionalexpr
  34     return ( optionalexpr )
  35             This returns a value from a function.  Functions always
  36             have a return value, even if this statement is not used.
  37             If no return statement is executed, or if no expression
  38             is specified in the return statement, then the return
  39             value from the function is the null type.
  40
  41
  42     switch
  43     ------
  44     switch (expr) { caseclauses }
  45             Switch statements work similarly to C, except for the
  46             following.  A switch can be done on any type of value,
  47             and the case statements can be of any type of values.
  48             The case statements can also be expressions calculated
  49             at runtime.  The calculator compares the switch value
  50             with each case statement in the order specified, and
  51             selects the first case which matches.  The default case
  52             is the exception, and only matches once all other cases
  53             have been tested.
  54
  55
  56     matrix
  57     ------
  58     mat variable [dimension] [dimension] ...
  59     mat variable [dimension, dimension, ...]
  60     mat variable [] = { value, ... }
  61             This creates a matrix variable with the specified dimensions.
  62             Matrices can have from 1 to 4 dimensions.  When specifying
  63             multiple dimensions, you can use either the standard C syntax,
  64             or else you can use commas for separating the dimensions.
  65             For example, the following two statements are equivalent,
  66             and so will create the same two dimensional matrix:
  67
  68                     mat foo[3][6];
  69                     mat foo[3,6];
  70
  71             By default, each dimension is indexed starting at zero,
  72             as in normal C, and contains the specified number of
  73             elements.  However, this can be changed if a colon is
  74             used to separate two values.  If this is done, then the
  75             two values become the lower and upper bounds for indexing.
  76             This is convenient, for example, to create matrices whose
  77             first row and column begin at 1.  Examples of matrix
  78             definitions are:
  79
  80                     mat x[3]    one dimension, bounds are 0-2
  81                     mat foo[4][5]       two dimensions, bounds are 0-3 and 0-4
  82                     mat a[-7:7] one dimension, bounds are (-7)-7
  83                     mat s[1:9,1:9]      two dimensions, bounds are 1-9 and 1-9
  84
  85             Note that the MAT statement is not a declaration, but is
  86             executed at runtime.  Within a function, the specified
  87             variable must already be defined, and is just converted to
  88             a matrix of the specified size, and all elements are set
  89             to the value of zero.  For convenience, at the top level
  90             command level, the MAT command automatically defines a
  91             global variable of the specified name if necessary.
  92
  93             Since the MAT statement is executed, the bounds on the
  94             matrix can be full expressions, and so matrices can be
  95             dynamically allocated.  For example:
  96
  97                     size = 20;
  98                     mat data[size*2];
  99
 100             allocates a matrix which can be indexed from 0 to 39.
 101
 102             Initial values for the elements of a matrix can be specified
 103             by following the bounds information with an equals sign and
 104             then a list of values enclosed in a pair of braces.  Even if
 105             the matrix has more than one dimension, the elements must be
 106             specified as a linear list.  If too few values are specified,
 107             the remaining values are set to zero.  If too many values are
 108             specified, a runtime error will result.  Examples of some
 109             initializations are:
 110
 111                     mat table1[5] = {77, 44, 22};
 112                     mat table2[2,2] = {1, 2, 3, 4};
 113
 114             When an initialization is done, the bounds of the matrix
 115             can optionally be left out of the square brackets, and the
 116             correct bounds (zero based) will be set.  This can only be
 117             done for one-dimensional matrices.  An example of this is:
 118
 119                     mat fred[] = {99, 98, 97};
 120
 121             The MAT statement can also be used in declarations to set
 122             variables as being matrices from the beginning.  For example:
 123
 124                     local mat temp[5];
 125                     static mat strtable[] = {"hi", "there", "folks");
 126
 127
 128     object
 129     ------
 130     obj type { elementnames } optionalvariables
 131     obj type variable
 132             These create a new object type, or create one or more
 133             variables of the specified type.  For this calculator,
 134             an object is just a structure which is implicitly acted
 135             on by user defined routines.  The user defined routines
 136             implement common operations for the object, such as plus
 137             and minus, multiply and divide, comparison and printing.
 138             The calculator will automatically call these routines in
 139             order to perform many operations.
 140
 141             To create an object type, the data elements used in
 142             implementing the object are specified within a pair
 143             of braces, separated with commas.  For example, to
 144             define an object will will represent points in 3-space,
 145             whose elements are the three coordinate values, the
 146             following could be used:
 147
 148                     obj point {x, y, z};
 149
 150             This defines an object type called point, whose elements
 151             have the names x, y, and z.  The elements are accessed
 152             similarly to structure element accesses, by using a period.
 153             For example, given a variable 'v' which is a point object,
 154             the three coordinates of the point can be referenced by:
 155
 156                     v.x
 157                     v.y
 158                     v.z
 159
 160             A particular object type can only be defined once, and
 161             is global throughout all functions.  However, different
 162             object types can be used at the same time.
 163
 164             In order to create variables of an object type, they
 165             can either be named after the right brace of the object
 166             creation statement, or else can be defined later with
 167             another obj statement.  To create two points using the
 168             second (and most common) method, the following is used:
 169
 170                     obj point p1, p2;
 171
 172             This statement is executed, and is not a declaration.
 173             Thus within a function, the variables p1 and p2 must have
 174             been previously defined, and are just changed to be the
 175             new object type.  For convenience, at the top level command
 176             level, object variables are automatically defined as being
 177             global when necessary.
 178
 179             Initial values for an object can be specified by following
 180             the variable name by an equals sign and a list of values
 181             enclosed in a pair of braces.  For example:
 182
 183                     obj point pt = {5, 6};
 184
 185             The OBJ statement can also be used in declarations to set
 186             variables as being objects from the beginning.  If multiple
 187             variables are specified, then each one is defined as the
 188             specified object type.  Examples of declarations are:
 189
 190                     local obj point temp1;
 191                     static obj point temp2 = {4, 3};
 192                     global obj point p1, p2, p3;
 193
 194
 195     print expressions
 196     -----------------
 197     print expr
 198     print expr, ... expr
 199     print expr: ... expr
 200             For interactive expression evaluation, the values of all
 201             typed-in expressions are automatically displayed to the
 202             user.  However, within a function or loop, the printing of
 203             results must be done explicitly.  This can be done using
 204             the 'printf' or 'fprintf' functions, as in standard C, or
 205             else by using the built-in 'print' statement.  The advantage
 206             of the print statement is that a format string is not needed.
 207             Instead, the given values are simply printed with zero or one
 208             spaces between each value.
 209
 210             Print accepts a list of expressions, separated either by
 211             commas or colons.  Each expression is evaluated in order
 212             and printed, with no other output, except for the following
 213             special cases.  The comma which separates expressions prints
 214             a single space, and a newline is printed after the last
 215             expression unless the statement ends with a colon.  As
 216             examples:
 217
 218                     print 3, 4;                 prints "3 4" and newline.
 219                     print 5:;                   prints "5" with no newline.
 220                     print 'a' : 'b' , 'c';      prints "ab c" and newline.
 221                     print;                      prints a newline.
 222
 223             For numeric values, the format of the number depends on the
 224             current "mode" configuration parameter.  The initial mode
 225             is to print real numbers, but it can be changed to other
 226             modes such as exponential, decimal fractions, or hex.
 227
 228             If a matrix or list is printed, then the elements contained
 229             within the matrix or list will also be printed, up to the
 230             maximum number specified by the "maxprint" configuration
 231             parameter.  If an element is also a matrix or a list, then
 232             their values are not recursively printed.  Objects are printed
 233             using their user-defined routine.  Printing a file value
 234             prints the name of the file that was opened.
 235
 236
 237     Also see the help topic:
 238
 239             command         top level commands
 240             expression      calc expression syntax
 241             builtin         calc builtin functions
 242             usage           how to invoke the calc command and calc -options
 243