c_cpp/etc/calc/help/address

   1 NAME
   2     & - address operator
   3
   4 SYNOPSIS
   5     &X
   6
   7 TYPES
   8     X           expression specifying an octet, lvalue, string or number
   9
  10     return      pointer
  11
  12 DESCRIPTION
  13     &X returns the address at which information for determining the current
  14     value of X is stored.  After an assignment as in p = &X, the
  15     value of X is accessible by *p so long as the connection between p
  16     and the value is not broken by relocation of the information or by the
  17     value ceasing to exist.  Use of an address after the connection
  18     is broken is unwise since the calculator may use that address for other
  19     purposes; the consequences of attempting to write data to, or
  20     otherwise accessing, such a vacated address may be catastrophic.
  21
  22     An octet is normally expressed by B[i] where B is a block and
  23     0 <= i < sizeof(B).  &B[i] then returns the address at which this
  24     octet is located until the block is freed or relocated.  Freeing
  25     of an unnamed block B occurs when a new value is assigned to B or
  26     when B ceases to exist; a named block B is freed by blkfree(B).
  27     A block is relocated when an operation like copying to B requires
  28     a change of sizeof(B).
  29
  30     An lvalue may be expressed by an identifier for a variable, or by
  31     such an identifier followed by one or more qualifiers compatible with
  32     the type of values associated with the variable and earlier qualifiers.
  33     If an identifier A specifies a global or static variable, the address
  34     &A is permanently associated with that variable.  For a local variable
  35     or function parameter A, the association of the variable with &A
  36     is limited to each occasion when the function is called.  If X specifies a
  37     component or element of a matrix or object, connection of
  38     &X with that component or element depends only on the continued existence
  39     of the matrix or object.  For example, after
  40
  41         ; mat A[3]
  42
  43     the addresses &A[0], &A[1], &A[2] locate the three elements
  44     of the matrix specified by A until another value is assigned to A, etc.
  45     Note one difference from C in that &A[0] is not the same as A.
  46
  47     An element of a list has a fixed address while the list exists and
  48     the element is not removed by pop(), remove(), or delete(); the index
  49     of the element changes if an element is pushed onto the list, or if
  50     earlier elements are popped or deleted.
  51
  52     Elements of an association have fixed addresses so long as the association
  53     exists.  If A[a,b,...] has not been defined for the association A,
  54     &A[a,b,...] returns the constant address of a particular null value.
  55
  56     Some other special values have fixed addresses; e.g. the old value (.).
  57
  58     Some arithmetic operations are defined for addresses but these should
  59     be used only for octets or components of a matrix or object where the
  60     results refer to octets in the same block or existing components of the
  61     same matrix or object.  For example, immediately after
  62
  63         ; mat A[10]
  64         ; p = &A[5]
  65
  66     it is permitted to use expressions like p + 4, p - 5, p++ .
  67
  68     Strings defined literally have fixed addresses, e.g., after
  69
  70         ; p = &"abc"
  71         ; A = "abc"
  72
  73     the address &*A of the value of A will be equal to p.
  74
  75     Except in cases like strcat(A, "") when *A identified with a literal
  76     string as above, definitions of string values using strcat() or substr()
  77     will copy the relevant strings to newly allocated addresses which will
  78     be useable only while the variables retain these defined values.
  79     For example, after
  80
  81         ; B = C = strcat("a", "bc");
  82
  83     &*B and &*C will be different.  If p is defined by p = &*B, p should
  84     not be used after a new value is assigned to B, or B ceases to exist,
  85     etc.
  86
  87     When compilation of a function encounters for the first time a particular
  88     literal number or the result of simple arithmetic operations (like +, -, *,
  89     or /) on literal numbers, that number is assigned to a particular
  90     address which is then used for later similar occurrences of that number
  91     so long as the number remains associated with at least one function or
  92     lvalue.  For example, after
  93
  94         ; x = 27;
  95         ; y = 3 * 9;
  96         ; define f(a) = 27 + a;
  97
  98     the three occurrences of 27 have the same address which may be displayed
  99     by any of &27, &*x, &*y and &f(0).  If x and y are assigned
 100     other values and f is redefined or undefined and the 27 has not been
 101     stored elsewhere (e.g. as the "old value" or in another function
 102     definition or as an element in an association), the address assigned at
 103     the first occurrence of 27 will be freed and calc may later use it for
 104     another number.
 105
 106     When a function returns a number value, that number value is usually
 107     placed at a newly allocated address, even if an equal number is stored
 108     elsewhere.  For example calls to f(a), as defined above, with the same
 109     non-zero value for a will be assigned to different addresses as can be
 110     seen from printing &*A, &*B, &*C after
 111
 112         ; A = f(2); B = f(2); C = f(2);
 113
 114     (the case of f(0) is exceptional since 27 + 0 simply copies the 27
 115     rather than creating a new number value).  Here it is clearly more
 116     efficient to use
 117
 118         ; A = B = C = f(2);
 119
 120     which, not only performs the addition in f() only once, but stores the
 121     number values for A, B and C at the same address.
 122
 123     Whether a value V is a pointer and if so, its type, is indicated by the
 124     value returned by isptr(V): 1, 2, 3, 4 for octet-, value-, string-
 125     and number-pointer respectively, and 0 otherwise.
 126
 127     The output when addresses are printed consists of a description (o_ptr,
 128     v_ptr, s_ptr, n_ptr) followed by : and the address printed in
 129     %p format.
 130
 131     Iteration of & is not permitted; &&X causes a "non-variable operand"
 132     scan error.
 133
 134 EXAMPLE
 135     Addresses for particular systems may differ from those displayed here.
 136
 137     ; mat A[3]
 138     ; B = blk()
 139
 140     ; print &A, &A[0], &A[1]
 141     v-ptr: 1400470d0 v-ptr: 140044b70 v-ptr: 140044b80
 142
 143     ; print &B, &B[0], &B[1]
 144     v-ptr: 140047130 o-ptr: 140044d00 o-ptr: 140044d01
 145
 146     ; a = A[0] = 27
 147     ; print &*a, &*A[0]. &27
 148     n_ptr: 14003a850 n_ptr: 14003a850 n_ptr: 14003a850
 149
 150     ; a = A[0] = "abc"
 151     ; print &*a, &*A[0], &"abc"
 152     s_ptr: 14004cae0 s_ptr: 14004cae0 s_ptr: 14004cae0
 153
 154 LIMITS
 155     none
 156
 157 LINK LIBRARY
 158     none
 159
 160 SEE ALSO
 161     dereference, isptr
 162
 163 ## Copyright (C) 1999-2006  Landon Curt Noll
 164 ##
 165 ## Calc is open software; you can redistribute it and/or modify it under
 166 ## the terms of the version 2.1 of the GNU Lesser General Public License
 167 ## as published by the Free Software Foundation.
 168 ##
 169 ## Calc is distributed in the hope that it will be useful, but WITHOUT
 170 ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 171 ## or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General
 172 ## Public License for more details.
 173 ##
 174 ## A copy of version 2.1 of the GNU Lesser General Public License is
 175 ## distributed with calc under the filename COPYING-LGPL.  You should have
 176 ## received a copy with calc; if not, write to Free Software Foundation, Inc.
 177 ## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 178 ##
 179 ## @(#) $Revision: 30.1 $
 180 ## @(#) $Id: address,v 30.1 2007/03/16 11:10:42 chongo Exp $
 181 ## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/address,v $
 182 ##
 183 ## Under source code control:   1997/09/06 20:03:34
 184 ## File existed as early as:    1997
 185 ##
 186 ## chongo <was here> /\oo/\     http://www.isthe.com/chongo/
 187 ## Share and enjoy!  :-)        http://www.isthe.com/chongo/tech/comp/calc/