source: project/chicken/trunk/manual/Locations @ 10513

Last change on this file since 10513 was 10513, checked in by Ivan Raikov, 11 years ago

Version increased to 3.1.6

File size: 2.0 KB
Line 
1[[tags: manual]]
2
3[[toc:]]
4
5
6== Locations
7
8It is also possible to define variables containing unboxed C data,
9so called ''locations''. It should be noted that locations may
10only contain simple data, that is: everything that fits into a
11machine word, and double-precision floating point values.
12
13
14
15=== define-location
16
17 [syntax] (define-location NAME TYPE [INIT])
18
19Identical to {{(define-external NAME TYPE [INIT])}}, but the variable
20is not accessible from outside of the current compilation unit (it is
21declared {{static}}).
22
23=== let-location
24
25 [syntax] (let-location ((NAME TYPE [INIT]) ...) BODY ...)
26
27Defines a lexically bound location.
28
29=== location
30
31 [syntax] (location NAME)
32 [syntax] (location X)
33
34This form returns a pointer object
35that contains the address of the variable {{NAME}}.
36If the argument to {{location}} is not a location defined by {{define-location}},
37{{define-external}} or {{let-location}}, then
38
39 (location X)
40
41is essentially equivalent to
42
43 (make-locative X)
44
45(See the manual chapter or {{locatives}} for more information about
46locatives.
47
48Note that {{(location X)}} may be abbreviated as {{#$X}}.
49
50<enscript highlight=scheme>
51(define-external foo int)
52((foreign-lambda* void (((c-pointer int) ip)) "*ip = 123;")
53  (location foo))
54foo                                                                               ==> 123
55</enscript>
56
57This facility is especially useful in situations, where a C function
58returns more than one result value:
59
60<enscript highlight=scheme>
61#>
62#include <math.h>
63<#
64
65(define modf
66  (foreign-lambda double "modf" double (c-pointer double)) )
67
68(let-location ([i double])
69  (let ([f (modf 1.99 (location i))])
70    (print "i=" i ", f=" f) ) )
71</enscript>
72
73See [[location-and-c-string-star|location and c-string*]] for a tip on returning a {{c-string*}} type.
74
75{{location}} returns a value of type {{c-pointer}}, when given
76the name of a callback-procedure defined with {{define-external}}.
77
78Previous: [[Callbacks]]
79
80Next: [[Other support procedures]]
Note: See TracBrowser for help on using the repository browser.