Changeset 27163 in project


Ignore:
Timestamp:
08/02/12 18:54:21 (7 years ago)
Author:
juergen
Message:

version 0.8 of tuples

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/tuples

    r26087 r27163  
    1010== Documentation
    1111
    12 In this implementation tuples are implemented in the Design by Contract style, i.e. using the contracts module. A corollary of this is, that the documentation is included in the module. By convention, there is a routine with the module's name, tuples, which when called with no argument
    13 
    14   (tuples)
    15 
    16 shows the exported contract-checked symbols, and called with one of its symbols, e.g.
    17 
    18   (tuples 'tuple->list)
    19 
    20 shows the documentation of this symbol in all it's glory, i.e. together with call-structure, docstring, assumptions and propositions.
    21 
    22 Note that most contract-checked routines have brethren whith identical signature which are not contract-checked and are not exported. They are prefixed with an % sign and used internally, especially for contract-checking, thus avoiding double-checking.
     12In this implementation skiplists are implemented in the Design by
     13Contract style, i.e. using the contracts module. A corollary of this is,
     14that the documentation is included in one of the two modules in form of
     15a procedure with the module's name. Apart from this documentation
     16procedure the two modules, %tuples and tuples, have the same
     17interface.  The first module contains the raw implementations of the
     18procedures, the second imports the first with prefix % and wraps those
     19prefixed routines with contracts.
     20
     21==== tuples
     22
     23<procedure>(tuples [sym])</procedure>
     24
     25returns all available routines of the module when called without an
     26argument, but when called with one of these routines as a symbol,
     27returns its contract and documentation string.
    2328
    2429Another way to get the complete documentation is to use print-doclist from the contracts module. Issuing
    2530
     31<enscript highlight=scheme>
    2632  (import tuples (only contracts print-doclist))
    2733  (with-output-to-file "tuples.docu" (lambda () (print-doclist)))
    28 
    29 you'll get a file tuples.docu with the following content
    30 
    31         triple-right
    32         ------------
    33         (triple-right tup)
    34         returns the right item of a triple
    35 
    36         triple-middle
    37         -------------
    38         (triple-middle tup)
    39         returns the middle item of a triple
    40 
    41         triple-left
    42         -----------
    43         (triple-left tup)
    44         returns the left item of a triple
    45 
    46         triple
    47         ------
    48         (triple x y z)
    49         constructor for a tuple storing two items
    50 
    51         triple?
    52         -------
    53         (triple? x)
    54         tests for a tuple storing two items
    55 
    56         couple-right
    57         ------------
    58         (couple-right tup)
    59         returns the right item of a couple
    60 
    61         couple-left
    62         -----------
    63         (couple-left tup)
    64         returns the left item of a couple
    65 
    66         couple
    67         ------
    68         (couple x y)
    69         constructor for a tuple storing two items
    70 
    71         couple?
    72         -------
    73         (couple? x)
    74         tests for a tuple storing two items
    75 
    76         single-set!
    77         -----------
    78         (single-set! sg arg)
    79         replaces state of sg with arg
    80         (domain (%single? sg) (true? arg))
    81         (effect (state (%tuple-state sg) arg))
    82 
    83         single-ref
    84         ----------
    85         (single-ref sg)
    86         returns the state of the single object sg
    87         (domain (%single? sg))
    88 
    89         single
    90         ------
    91         (single xpr)
    92         package xpr into a box so that it can be modified
    93         (domain (true? xpr))
    94         (range (%single? result))
    95 
    96         single?
    97         -------
    98         (single? xpr)
    99         check, if xpr evaluates to a single
    100 
    101         empty
    102         -----
    103         (empty)
    104         constructor for an empty tuple
    105 
    106         empty?
    107         ------
    108         (empty? x)
    109         tests for an empty tuple
    110 
    111         tuple-for-each
    112         --------------
    113         (tuple-for-each proc tup)
    114         apply a one parameter procedure to each item of tup
    115         (domain (%tuple? tup) (procedure? proc) a one parameter procedure)
    116 
    117         tuple->list
    118         -----------
    119         (tuple->list tup)
    120         transforms a tuple into a list
    121         (domain (%tuple? tup))
    122         (range (list? result))
    123 
    124         tuple-find
    125         ----------
    126         (tuple-find tup item compare?)
    127         checks by comparing with compare? if item is contained in tup
    128         (domain (%tuple? tup) (procedure? compare?) a two parameter predicate)
    129         (range (or (not result) (and (cardinal? result) (< result (%tuple-length tup)))))
    130 
    131         tuple-right
    132         -----------
    133         (tuple-right tup)
    134         returns the rightmost item of tup
    135         (domain (%tuple? tup) (>= (%tuple-length tup) 2))
    136 
    137         tuple-left
    138         ----------
    139         (tuple-left tup)
    140         returns the leftmost item of tup
    141         (domain (%tuple? tup) (positive? (%tuple-length tup)))
    142 
    143         tuple-ref
    144         ---------
    145         (tuple-ref tup n)
    146         returns the n'th item of tup, counting from zero
    147         (domain (%tuple? tup) (cardinal? n) (< n (%tuple-length tup)))
    148 
    149         tuple-length
    150         ------------
    151         (tuple-length tup)
    152         returns the number of tuple items
    153         (domain (%tuple? tup))
    154         (range (cardinal? result))
    155 
    156         tuple-copy
    157         ----------
    158         (tuple-copy tup . interval)
    159         constructing a subtuple with tup data from interval
    160         (domain (%tuple? tup)
    161                                         (<= (length interval) 2)
    162                                         ((list-of? cardinal?) interval)
    163                                         (apply <= (append interval (list (%tuple-length tup)))))
    164         (range (%tuple? result))
    165 
    166         tuple-append
    167         ------------
    168         (tuple-append . tups)
    169         constructs a new tuple by concatenating several others
    170         (domain ((list-of? tuple?) tups))
    171         (range (%tuple? result))
    172 
    173         tuple-map
    174         ---------
    175         (tuple-map fn tup)
    176         constructs a new tuple by mapping each item of tup with function fn
    177         (domain (%tuple? tup) (procedure? fn) a one parameter function)
    178         (range (%tuple? result))
    179 
    180         list->tuple
    181         -----------
    182         (list->tuple lst)
    183         transforms a list into a tuple
    184         (domain (list? lst))
    185         (range (%tuple? result))
    186 
    187         tuple
    188         -----
    189         (tuple . args)
    190         tuple constructor
    191         (domain (true? args))
    192         (range (%tuple? result))
    193 
    194         tuple-of?
    195         ---------
    196         (tuple-of? ok?)
    197         checks, if each tuple item satisfies predicate ok?
    198         (domain (procedure? ok?) ok? is a one parameter predicate)
    199         (range (procedure? result) result is a one parameter predicate)
    200 
    201         tuple?
    202         ------
    203         (tuple? xpr)
    204         checks if xpr evaluates to a tuple
     34</enscript>
     35
     36you'll get a file tuples.docu which is the basis for the following
     37documentation.
     38
     39==== triple-right
     40
     41<procedure>(triple-right tup)</procedure>
     42
     43returns the right item of a triple
     44
     45==== triple-middle
     46
     47<procedure>(triple-middle tup)</procedure>
     48
     49returns the middle item of a triple
     50
     51==== triple-left
     52
     53<procedure>(triple-left tup)</procedure>
     54
     55returns the left item of a triple
     56
     57==== triple
     58
     59<procedure>(triple x y z)</procedure>
     60
     61constructor for a tuple storing two items
     62
     63==== triple?
     64
     65<procedure>(triple? x)</procedure>
     66
     67tests for a tuple storing two items
     68
     69==== couple-right
     70
     71<procedure>(couple-right tup)</procedure>
     72
     73returns the right item of a couple
     74
     75==== couple-left
     76
     77<procedure>(couple-left tup)</procedure>
     78
     79returns the left item of a couple
     80
     81==== couple
     82
     83<procedure>(couple x y)</procedure>
     84
     85constructor for a tuple storing two items
     86
     87==== couple?
     88
     89<procedure>(couple? x)</procedure>
     90
     91tests for a tuple storing two items
     92
     93==== single-set!
     94
     95<procedure>(single-set! sg arg)</procedure>
     96
     97<enscript highlight=scheme>
     98(domain (%single? sg) (true? arg))
     99(effect (state (%tuple-state sg) arg))
     100</enscript>
     101
     102replaces state of sg with arg
     103
     104==== single-ref
     105
     106<procedure>(single-ref sg)</procedure>
     107
     108<enscript highlight=scheme>
     109(domain (%single? sg))
     110</enscript>
     111
     112returns the state of the single object sg
     113
     114==== single
     115
     116<procedure>(single xpr)</procedure>
     117
     118<enscript highlight=scheme>
     119(domain (true? xpr))
     120(range (%single? result))
     121</enscript>
     122
     123package xpr into a box so that it can be modified
     124
     125==== single?
     126
     127<procedure>(single? xpr)</procedure>
     128
     129check, if xpr evaluates to a single
     130
     131==== empty
     132
     133<procedure>(empty)</procedure>
     134
     135constructor for an empty tuple
     136
     137==== empty?
     138
     139<procedure>(empty? x)</procedure>
     140
     141tests for an empty tuple
     142
     143==== tuple-for-each
     144
     145<procedure>(tuple-for-each proc tup)</procedure>
     146
     147<enscript highlight=scheme>
     148(domain (%tuple? tup) (procedure? proc) a one parameter procedure)
     149</enscript>
     150
     151apply a one parameter procedure to each item of tup
     152
     153==== tuple->list
     154
     155<procedure>(tuple->list tup)</procedure>
     156
     157<enscript highlight=scheme>
     158(domain (%tuple? tup))
     159(range (list? result))
     160</enscript>
     161
     162transforms a tuple into a list
     163
     164==== tuple-find
     165
     166<procedure>(tuple-find tup item compare?)</procedure>
     167
     168<enscript highlight=scheme>
     169(domain (%tuple? tup) (procedure? compare?) a two parameter predicate)
     170(range (or (not result) (and (cardinal? result) (< result (%tuple-length tup)))))
     171</enscript>
     172
     173checks by comparing with compare? if item is contained in tup
     174
     175==== tuple-right
     176
     177<procedure>(tuple-right tup)</procedure>
     178
     179<enscript highlight=scheme>
     180(domain (%tuple? tup) (>= (%tuple-length tup) 2))
     181</enscript>
     182
     183returns the rightmost item of tup
     184
     185==== tuple-left
     186
     187<procedure>(tuple-left tup)</procedure>
     188
     189<enscript highlight=scheme>
     190(domain (%tuple? tup) (positive? (%tuple-length tup)))
     191</enscript>
     192
     193returns the leftmost item of tup
     194
     195==== tuple-ref
     196
     197<procedure>(tuple-ref tup n)</procedure>
     198
     199<enscript highlight=scheme>
     200(domain (%tuple? tup) (cardinal? n) (< n (%tuple-length tup)))
     201</enscript>
     202
     203returns the n'th item of tup, counting from zero
     204
     205==== tuple-length
     206
     207<procedure>(tuple-length tup)</procedure>
     208
     209<enscript highlight=scheme>
     210(domain (%tuple? tup))
     211(range (cardinal? result))
     212</enscript>
     213
     214returns the number of tuple items
     215
     216==== tuple-copy
     217
     218<procedure>(tuple-copy tup . interval)</procedure>
     219
     220<enscript highlight=scheme>
     221(domain (%tuple? tup)
     222                                (<= (length interval) 2)
     223                                ((list-of? cardinal?) interval)
     224                                (apply <= (append interval (list (%tuple-length tup)))))
     225(range (%tuple? result))
     226</enscript>
     227
     228constructing a subtuple with tup data from interval
     229
     230==== tuple-append
     231
     232<procedure>(tuple-append . tups)</procedure>
     233
     234<enscript highlight=scheme>
     235(domain ((list-of? tuple?) tups))
     236(range (%tuple? result))
     237</enscript>
     238
     239constructs a new tuple by concatenating several others
     240
     241==== tuple-map
     242
     243<procedure>(tuple-map fn tup)</procedure>
     244
     245<enscript highlight=scheme>
     246(domain (%tuple? tup) (procedure? fn) a one parameter function)
     247(range (%tuple? result))
     248</enscript>
     249
     250constructs a new tuple by mapping each item of tup with function fn
     251
     252==== list->tuple
     253
     254<procedure>(list->tuple lst)</procedure>
     255
     256<enscript highlight=scheme>
     257(domain (list? lst))
     258(range (%tuple? result))
     259</enscript>
     260
     261transforms a list into a tuple
     262
     263==== tuple
     264
     265<procedure>(tuple . args)</procedure>
     266
     267<enscript highlight=scheme>
     268(domain (true? args))
     269(range (%tuple? result))
     270</enscript>
     271
     272tuple constructor
     273
     274==== tuple-of?
     275
     276<procedure>(tuple-of? ok?)</procedure>
     277
     278<enscript highlight=scheme>
     279(domain (procedure? ok?) ok? is a one parameter predicate)
     280(range (procedure? result) result is a one parameter predicate)
     281</enscript>
     282
     283checks, if each tuple item satisfies predicate ok?
     284
     285==== tuple?
     286
     287<procedure>(tuple? xpr)</procedure>
     288
     289checks if xpr evaluates to a tuple
    205290
    206291
     
    211296== Last update
    212297
    213 Mar 07, 2012
     298Aug 02, 2012
    214299
    215300== Author
     
    250335== Version History
    251336
     337; 0.8 : code split into two modules
    252338; 0.7 : single-state and single-state! renamed to single-ref and single-set!
    253339; 0.6 : contracts rewritten
Note: See TracChangeset for help on using the changeset viewer.