Ticket #908: Unit-library-symbols-section.diff

File Unit-library-symbols-section.diff, 5.5 KB (added by felix winkelmann, 10 years ago)
  • manual/Unit

    diff --git a/manual/Unit library b/manual/Unit library
    index 1fed128..68891a5 100644
    a b equivalent to {{(list->string (reverse LIST))}}, but much more efficient. 
    793793
    794794
    795795
    796 === Generating uninterned symbols
     796=== Symbols
    797797
    798 ==== gensym
     798==== Symbol utilities
     799
     800===== symbol-append
     801
     802<procedure>(symbol-append SYMBOL1 ...)</procedure>
     803
     804Creates a new symbol from the concatenated names of the argument symbols
     805{{(SYMBOL1 ...)}}.
     806
     807==== Uninterned symbols ("gensyms")
     808
     809Symbols may be "interned" or "uninterned". Interned symbols are
     810registered in a global table, and when read back from a port are
     811identical to a symbol written before:
     812
     813<enscript highlight=scheme>
     814(define sym 'foo)
     815
     816(eq? sym (with-input-from-string
     817            (with-output-to-string
     818              (lambda () (write sym)))
     819            read))
     820
     821  => #t
     822</enscript>
     823
     824Uninterned symbols on the other hand are not globally registered and so
     825mulitple symbols with the same name may coexist:
     826
     827<enscript highlight=scheme>
     828(define sym (gensym 'foo))   ; sym is a uninterned symbol like "foo42"
     829
     830(eq? sym (with-input-from-string    ; the symbol read will be an interned symbol
     831            (with-output-to-string
     832              (lambda () (write sym)))
     833            read))
     834
     835  => #f
     836
     837(eq? (string->uninterned-symbol "foo") (string->uninterned-symbol "foo"))
     838
     839  => #f
     840</enscript>
     841
     842Use uninterned symbols if you need to generate unique values that
     843can be compared quickly, for example as keys into a hash-table
     844or association list. Note that uninterned symbols loose their
     845uniqueness property when written to a file and read back in, as
     846in the example above.
     847
     848
     849===== gensym
    799850
    800851<procedure>(gensym [STRING-OR-SYMBOL])</procedure>
    801852
    Returns a newly created uninterned symbol. If an argument is provided, 
    803854the new symbol is prefixed with that argument.
    804855
    805856
    806 ==== string->uninterned-symbol
     857===== string->uninterned-symbol
    807858
    808859<procedure>(string->uninterned-symbol STRING)</procedure>
    809860
    810861Returns a newly created, unique symbol with the name {{STRING}}.
    811862
    812863
    813 ==== symbol-append
     864==== Property lists
    814865
    815 <procedure>(symbol-append SYMBOL1 ...)</procedure>
     866As in other Lisp dialects, CHICKEN supports "property lists" associated with symbols.
     867Properties are accessible via a key that can be any kind of value but which will
     868be compared using {{eq?}}.
    816869
    817 Creates a new interned symbol from the concatenated names of the argument symbols
    818 {{(SYMBOL1 ...)}}.
     870===== get
     871
     872<procedure>(get SYMBOL PROPERTY [DEFAULT])</procedure>
     873
     874Returns the value stored under the key {{PROPERTY}} in the property
     875list of {{SYMBOL}}. If no such property is stored, returns
     876{{DEFAULT}}. The {{DEFAULT}} is optional and defaults to {{#f}}.
     877
     878===== put!
     879
     880<procedure>(put! SYMBOL PROPERTY VALUE)</procedure>
     881setter: (set! (get SYMBOL PROPERTY) VALUE)
     882
     883Stores {{VALUE}} under the key {{PROPERTY}} in the property list of
     884{{SYMBOL}} replacing any previously stored value.
     885
     886===== remprop!
     887
     888<procedure>(remprop! SYMBOL PROPERTY)</procedure>
     889
     890Deletes the first property matching the key {{PROPERTY}} in the property list
     891of {{SYMBOL}}. Returns {{#t}} when a deletion performed, and {{#f}} otherwise.
     892
     893===== symbol-plist
     894
     895<procedure>(symbol-plist SYMBOL)</procedure>
     896setter: (set! (symbol-plist SYMBOL) LST)
     897
     898Returns the property list of {{SYMBOL}} or sets it.
     899
     900===== get-properties
     901
     902<procedure>(get-properties SYMBOL PROPERTIES)</procedure>
     903
     904Searches the property list of {{SYMBOL}} for the first property with a key in
     905the list {{PROPERTIES}}. Returns 3 values: the matching property key, value,
     906and the tail of property list after the matching property. When no match found
     907all values are {{#f}}.
     908
     909{{PROPERTIES}} may also be an atom, in which case it is treated as a list of
     910one element.
    819911
    820912
    821913=== Standard Input/Output
    Returns a copy of the given read-table. You can access the currently active read 
    11521244with {{(current-read-table)}}.
    11531245
    11541246
    1155 === Property lists
    1156 
    1157 As in other Lisp dialects, CHICKEN supports "property lists" associated with symbols.
    1158 Properties are accessible via a key that can be any kind of value but which will
    1159 be compared using {{eq?}}.
    1160 
    1161 ==== get
    1162 
    1163 <procedure>(get SYMBOL PROPERTY [DEFAULT])</procedure>
    1164 
    1165 Returns the value stored under the key {{PROPERTY}} in the property
    1166 list of {{SYMBOL}}. If no such property is stored, returns
    1167 {{DEFAULT}}. The {{DEFAULT}} is optional and defaults to {{#f}}.
    1168 
    1169 ==== put!
    1170 
    1171 <procedure>(put! SYMBOL PROPERTY VALUE)</procedure>
    1172 setter: (set! (get SYMBOL PROPERTY) VALUE)
    1173 
    1174 Stores {{VALUE}} under the key {{PROPERTY}} in the property list of
    1175 {{SYMBOL}} replacing any previously stored value.
    1176 
    1177 ==== remprop!
    1178 
    1179 <procedure>(remprop! SYMBOL PROPERTY)</procedure>
    1180 
    1181 Deletes the first property matching the key {{PROPERTY}} in the property list
    1182 of {{SYMBOL}}. Returns {{#t}} when a deletion performed, and {{#f}} otherwise.
    1183 
    1184 ==== symbol-plist
    1185 
    1186 <procedure>(symbol-plist SYMBOL)</procedure>
    1187 setter: (set! (symbol-plist SYMBOL) LST)
    1188 
    1189 Returns the property list of {{SYMBOL}} or sets it.
    1190 
    1191 ==== get-properties
    1192 
    1193 <procedure>(get-properties SYMBOL PROPERTIES)</procedure>
    1194 
    1195 Searches the property list of {{SYMBOL}} for the first property with a key in
    1196 the list {{PROPERTIES}}. Returns 3 values: the matching property key, value,
    1197 and the tail of property list after the matching property. When no match found
    1198 all values are {{#f}}.
    1199 
    1200 {{PROPERTIES}} may also be an atom, in which case it is treated as a list of
    1201 one element.
    12021247
    12031248----
    12041249Previous: [[Exceptions]] Next: [[Unit eval]]