/[guile]/guile/guile-core/doc/ref/scheme-data.texi
ViewVC logotype

Diff of /guile/guile-core/doc/ref/scheme-data.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.16 by ossau, Wed Mar 27 21:55:31 2002 UTC revision 1.17 by ossau, Mon Apr 1 14:44:02 2002 UTC
# Line 1462  called with string containing unusual ch Line 1462  called with string containing unusual ch
1462  * String Searching::            Searching in strings.  * String Searching::            Searching in strings.
1463  * Alphabetic Case Mapping::     Convert the alphabetic case of strings.  * Alphabetic Case Mapping::     Convert the alphabetic case of strings.
1464  * Appending Strings::           Appending strings to form a new string.  * Appending Strings::           Appending strings to form a new string.
 * String Miscellanea::          Miscellaneous string procedures.  
1465  @end menu  @end menu
1466    
1467  @node String Syntax  @node String Syntax
# Line 1858  concatenation of the given strings, @var Line 1857  concatenation of the given strings, @var
1857  @end deffn  @end deffn
1858    
1859    
 @node String Miscellanea  
 @subsection String Miscellanea  
   
 This section contains all remaining string procedures.  
   
 @deffn {Scheme Procedure} string-ci->symbol str  
 @deffnx {C Function} scm_string_ci_to_symbol (str)  
 Return the symbol whose name is @var{str}.  @var{str} is  
 converted to lowercase before the conversion is done, if Guile  
 is currently reading symbols case-insensitively.  
 @end deffn  
   
   
1860  @node Regular Expressions  @node Regular Expressions
1861  @section Regular Expressions  @section Regular Expressions
1862  @tpindex Regular expressions  @tpindex Regular expressions
# Line 2213  to this cumbersome escape syntax. Line 2199  to this cumbersome escape syntax.
2199  @section Symbols  @section Symbols
2200  @tpindex Symbols  @tpindex Symbols
2201    
2202  Symbols have two main uses.  Crucially, they are used for denoting  Symbols in Scheme are widely used in three ways: as items of discrete
2203  variables in a Scheme program.  In addition, they are very useful for  data, as lookup keys for alists and hash tables, and to denote variable
2204  describing discrete literal data.  references.
2205    
2206  A symbol is an object with a name that consists of a string of  A @dfn{symbol} is similar to a string in that it is defined by a
2207  characters.  In the usual case (where the name doesn't include any  sequence of characters.  The sequence of characters is known as the
2208  characters that could be confused with other elements of Scheme syntax)  symbol's @dfn{name}.  In the usual case --- that is, where the symbol's
2209  a symbol can be written in a Scheme program by writing the sequence of  name doesn't include any characters that could be confused with other
2210  characters that make up the symbol's name.  For example, the read syntax  elements of Scheme syntax --- a symbol is written in a Scheme program by
2211  for the symbol named "multiply-by-2" is simply  writing the sequence of characters that make up the name, @emph{without}
2212    any quotation marks or other special syntax.  For example, the symbol
2213    whose name is ``multiply-by-2'' is written, simply:
2214    
2215  @lisp  @lisp
2216  multiply-by-2  multiply-by-2
2217  @end lisp  @end lisp
2218    
2219  Symbols, then, look rather like strings but without any quotation marks.  Notice how this differs from a @emph{string} with contents
2220  But there are several functional differences between them.  The first  ``multiply-by-2'', which is written with double quotation marks, like
2221  big functional difference between symbols and strings concerns  this:
 uniqueness.  If the same-looking string is read twice from two different  
 places in a program, the result is two @emph{distinguishable} string  
 objects whose contents just happen to be the same.  If, on the other  
 hand, the same-looking symbol is read twice from two different places in  
 a program, the result is the @emph{same} symbol object both times.  
2222    
2223  @lisp  @lisp
2224  (define str1 "hello")  "multiply-by-2"
2225  (define str2 "hello")  @end lisp
 (eq? str1 str2) @result{} #f  
2226    
2227    Looking beyond how they are written, symbols are different from strings
2228    in two important respects.
2229    
2230    The first important difference is uniqueness.  If the same-looking
2231    string is read twice from two different places in a program, the result
2232    is two @emph{different} string objects whose contents just happen to be
2233    the same.  If, on the other hand, the same-looking symbol is read twice
2234    from two different places in a program, the result is the @emph{same}
2235    symbol object both times.
2236    
2237    Given two read symbols, you can use @code{eq?} to test whether they are
2238    the same (that is, have the same name).  @code{eq?} is the most
2239    efficient comparison operator in Scheme, and comparing two symbols like
2240    this is as fast as comparing, for example, two numbers.  Given two
2241    strings, on the other hand, you must use @code{equal?} or
2242    @code{string=?}, which are much slower comparison operators, to
2243    determine whether the strings have the same contents.
2244    
2245    @lisp
2246  (define sym1 (quote hello))  (define sym1 (quote hello))
2247  (define sym2 (quote hello))  (define sym2 (quote hello))
2248  (eq? sym1 sym2) @result{} #t  (eq? sym1 sym2) @result{} #t
2249    
2250    (define str1 "hello")
2251    (define str2 "hello")
2252    (eq? str1 str2) @result{} #f
2253    (equal? str1 str2) @result{} #t
2254  @end lisp  @end lisp
2255    
2256  The second important difference is that symbols, unlike strings, are not  The second important difference is that symbols, unlike strings, are not
2257  self-evaluating.  An unquoted symbol is interpreted as a variable  self-evaluating.  This is why we need the @code{(quote @dots{})}s in the
2258  reference, and the result of evaluating that symbol is the corresponding  example above: @code{(quote hello)} evaluates to the symbol named
2259  variable's value.  (By the way, this is why we needed the @code{(quote  "hello" itself, whereas an unquoted @code{hello} is @emph{read} as the
2260  @dots{})}s in the example above: @code{(quote hello)} returns the symbol  symbol named "hello" and evaluated as a variable reference @dots{} about
2261  object named "hello" itself, whereas an unquoted @code{hello} would try  which more below (@pxref{Symbol Variables}).
 to find and dereference a variable associated with that symbol.)  
   
 For example, when the expression @code{(string-length "abcd")} is read  
 and evaluated, the sequence of characters @code{string-length} is read  
 as the symbol whose name is "string-length".  This symbol is associated  
 with a variable whose value is the procedure that implements string  
 length calculation.  Therefore evaluation of the @code{string-length}  
 symbol results in that procedure.  
   
 Although the use of symbols for variable references is undoubtedly their  
 most important role in Scheme, it is not documented further here.  See  
 instead @ref{Binding Constructs}, for how associations between symbols  
 and variables are created, and @ref{Modules}, for how those associations  
 are affected by Guile's module system.  The rest of this section  
 explains how symbols can also be used to represent discrete values, and  
 documents the procedures available that relate to symbols as data  
 objects @i{per se}.  
2262    
2263  @menu  @menu
2264  * Symbol Read Syntax::          Extended read syntax for symbols.  * Symbol Data::                 Symbols as discrete data.
2265    * Symbol Keys::                 Symbols as lookup keys.
2266    * Symbol Variables::            Symbols as denoting variables.
2267  * Symbol Primitives::           Operations related to symbols.  * Symbol Primitives::           Operations related to symbols.
 * Symbol Tables::               Collecting symbols into obarrays.  
 * Symbol Discrete::             Using symbols as discrete values.  
2268  * Symbol Props::                Function slots and property lists.  * Symbol Props::                Function slots and property lists.
2269    * Symbol Read Syntax::          Extended read syntax for symbols.
2270  * Symbol Uninterned::           Uninterned symbols.  * Symbol Uninterned::           Uninterned symbols.
2271  @end menu  @end menu
2272    
2273    
2274  @node Symbol Read Syntax  @node Symbol Data
2275  @subsection Extended Read Syntax for Symbols  @subsection Symbols as Discrete Data
2276    
2277  The read syntax for a symbol is a sequence of letters, digits, and  Numbers and symbols are similar to the extent that they both lend
2278  @dfn{extended alphabetic characters}, beginning with a character that  themselves to @code{eq?} comparison.  But symbols are more descriptive
2279  cannot begin a number.  In addition, the special cases of @code{+},  than numbers, because a symbol's name can be used directly to describe
2280  @code{-}, and @code{...} are read as symbols even though numbers can  the concept for which that symbol stands.
2281  begin with @code{+}, @code{-} or @code{.}.  
2282    For example, imagine that you need to represent some colours in a
2283    computer program.  Using numbers, you would have to choose arbitrarily
2284    some mapping between numbers and colours, and then take care to use that
2285    mapping consistently:
2286    
2287  Extended alphabetic characters may be used within identifiers as if  @lisp
2288  they were letters.  The set of extended alphabetic characters is:  ;; 1=red, 2=green, 3=purple
2289    
2290  @example  (if (eq? (colour-of car) 1)
2291  ! $ % & * + - . / : < = > ? @@ ^ _ ~      ...)
2292  @end example  @end lisp
2293    
2294  In addition to the standard read syntax defined above (which is taken  @noindent
2295  from R5RS (@pxref{Formal syntax,,,r5rs,The Revised^5 Report on  You can make the mapping more explicit and the code more readable by
2296  Scheme})), Guile provides an extended symbol read syntax that allows the  defining constants:
2297  inclusion of unusual characters such as space characters, newlines and  
2298  parentheses.  If (for whatever reason) you need to write a symbol  @lisp
2299  containing characters not mentioned above, you can do so as follows.  (define red 1)
2300    (define green 2)
2301    (define purple 3)
2302    
2303    (if (eq? (colour-of car) red)
2304        ...)
2305    @end lisp
2306    
2307    @noindent
2308    But the simplest and clearest approach is not to use numbers at all, but
2309    symbols whose names specify the colours that they refer to:
2310    
2311    @lisp
2312    (if (eq? (colour-of car) 'red)
2313        ...)
2314    @end lisp
2315    
2316    The descriptive advantages of symbols over numbers increase as the set
2317    of concepts that you want to describe grows.  Suppose that a car object
2318    can have other properties as well, such as whether it has or uses:
2319    
2320  @itemize @bullet  @itemize @bullet
2321  @item  @item
2322  Begin the symbol with the characters @code{#@{},  automatic or manual transmission
   
2323  @item  @item
2324  write the characters of the symbol and  leaded or unleaded fuel
   
2325  @item  @item
2326  finish the symbol with the characters @code{@}#}.  power steering (or not).
2327  @end itemize  @end itemize
2328    
2329  Here are a few examples of this form of read syntax.  The first symbol  @noindent
2330  needs to use extended syntax because it contains a space character, the  Then a car's combined property set could be naturally represented and
2331  second because it contains a line break, and the last because it looks  manipulated as a list of symbols:
 like a number.  
2332    
2333  @lisp  @lisp
2334  #@{foo bar@}#  (properties-of car1)
2335    @result{}
2336    (red manual unleaded power-steering)
2337    
2338  #@{what  (if (memq 'power-steering (properties-of car1))
2339  ever@}#      (display "Unfit people can drive this car.\n")
2340        (display "You'll need strong arms to drive this car!\n"))
2341    @print{}
2342    Unfit people can drive this car.
2343    @end lisp
2344    
2345  #@{4242@}#  Remember, the fundamental property of symbols that we are relying on
2346    here is that an occurrence of @code{'red} in one part of a program is an
2347    @emph{indistinguishable} symbol from an occurrence of @code{'red} in
2348    another part of a program; this means that symbols can usefully be
2349    compared using @code{eq?}.  At the same time, symbols have naturally
2350    descriptive names.  This combination of efficiency and descriptive power
2351    makes them ideal for use as discrete data.
2352    
2353    
2354    @node Symbol Keys
2355    @subsection Symbols as Lookup Keys
2356    
2357    Given their efficiency and descriptive power, it is natural to use
2358    symbols as the keys in an association list or hash table.
2359    
2360    To illustrate this, consider a more structured representation of the car
2361    properties example from the preceding subsection.  Rather than
2362    mixing all the properties up together in a flat list, we could use an
2363    association list like this:
2364    
2365    @lisp
2366    (define car1-properties '((colour . red)
2367                              (transmission . manual)
2368                              (fuel . unleaded)
2369                              (steering . power-assisted)))
2370  @end lisp  @end lisp
2371    
2372  Although Guile provides this extended read syntax for symbols,  Notice how this structure is more explicit and extensible than the flat
2373  widespread usage of it is discouraged because it is not portable and not  list.  For example it makes clear that @code{manual} refers to the
2374  very readable.  transmission rather than, say, the windows or the locking of the car.
2375    It also allows further properties to use the same symbols among their
2376    possible values without becoming ambiguous:
2377    
2378    @lisp
2379    (define car1-properties '((colour . red)
2380                              (transmission . manual)
2381                              (fuel . unleaded)
2382                              (steering . power-assisted)
2383                              (seat-colour . red)
2384                              (locking . manual)))
2385    @end lisp
2386    
2387    With a representation like this, it is easy to use the efficient
2388    @code{assq-XXX} family of procedures (@pxref{Association Lists}) to
2389    extract or change individual pieces of information:
2390    
2391    @lisp
2392    (assq-ref car1-properties 'fuel) @result{} unleaded
2393    (assq-ref car1-properties 'transmission) @result{} manual
2394    
2395    (assq-set! car1-properties 'seat-colour 'black)
2396    @result{}
2397    ((colour . red)
2398     (transmission . manual)
2399     (fuel . unleaded)
2400     (steering . power-assisted)
2401     (seat-colour . black)
2402     (locking . manual)))
2403    @end lisp
2404    
2405    Hash tables also have keys, and exactly the same arguments apply to the
2406    use of symbols in hash tables as in association lists.  The hash value
2407    that Guile uses to decide where to add a symbol-keyed entry to a hash
2408    table can be obtained by calling the @code{symbol-hash} procedure:
2409    
2410    @deffn {Scheme Procedure} symbol-hash symbol
2411    @deffnx {C Function} scm_symbol_hash (symbol)
2412    Return a hash value for @var{symbol}.
2413    @end deffn
2414    
2415    See @ref{Hash Tables} for information about hash tables in general, and
2416    for why you might choose to use a hash table rather than an association
2417    list.
2418    
2419    
2420    @node Symbol Variables
2421    @subsection Symbols as Denoting Variables
2422    
2423    When an unquoted symbol in a Scheme program is evaluated, it is
2424    interpreted as a variable reference, and the result of the evaluation is
2425    the appropriate variable's value.
2426    
2427    For example, when the expression @code{(string-length "abcd")} is read
2428    and evaluated, the sequence of characters @code{string-length} is read
2429    as the symbol whose name is "string-length".  This symbol is associated
2430    with a variable whose value is the procedure that implements string
2431    length calculation.  Therefore evaluation of the @code{string-length}
2432    symbol results in that procedure.
2433    
2434    The details of the connection between an unquoted symbol and the
2435    variable to which it refers are explained elsewhere.  See @ref{Binding
2436    Constructs}, for how associations between symbols and variables are
2437    created, and @ref{Modules}, for how those associations are affected by
2438    Guile's module system.
2439    
2440    
2441  @node Symbol Primitives  @node Symbol Primitives
2442  @subsection Operations Related to Symbols  @subsection Operations Related to Symbols
2443    
2444    Given any Scheme value, you can determine whether it is a symbol using
2445    the @code{symbol?} primitive:
2446    
2447  @rnindex symbol?  @rnindex symbol?
2448  @deffn {Scheme Procedure} symbol? obj  @deffn {Scheme Procedure} symbol? obj
2449  @deffnx {C Function} scm_symbol_p (obj)  @deffnx {C Function} scm_symbol_p (obj)
# Line 2344  Return @code{#t} if @var{obj} is a symbo Line 2451  Return @code{#t} if @var{obj} is a symbo
2451  @code{#f}.  @code{#f}.
2452  @end deffn  @end deffn
2453    
2454    Once you know that you have a symbol, you can obtain its name as a
2455    string by calling @code{symbol->string}.  Note that Guile differs by
2456    default from R5RS on the details of @code{symbol->string} as regards
2457    case-sensitivity:
2458    
2459    @rnindex symbol->string
2460    @deffn {Scheme Procedure} symbol->string s
2461    @deffnx {C Function} scm_symbol_to_string (s)
2462    Return the name of symbol @var{s} as a string.  By default, Guile reads
2463    symbols case-sensitively, so the string returned will have the same case
2464    variation as the sequence of characters that caused @var{s} to be
2465    created.
2466    
2467    If Guile is set to read symbols case-insensitively (as specified by
2468    R5RS), and @var{s} comes into being as part of a literal expression
2469    (@pxref{Literal expressions,,,r5rs, The Revised^5 Report on Scheme}) or
2470    by a call to the @code{read} or @code{string-ci->symbol} procedures,
2471    Guile converts any alphabetic characters in the symbol's name to
2472    lower case before creating the symbol object, so the string returned
2473    here will be in lower case.
2474    
2475    If @var{s} was created by @code{string->symbol}, the case of characters
2476    in the string returned will be the same as that in the string that was
2477    passed to @code{string->symbol}, regardless of Guile's case-sensitivity
2478    setting at the time @var{s} was created.
2479    
2480    It is an error to apply mutation procedures like @code{string-set!} to
2481    strings returned by this procedure.
2482    @end deffn
2483    
2484    Most symbols are created by writing them literally in code.  However it
2485    is also possible to create symbols programmatically using the following
2486    @code{string->symbol} and @code{string-ci->symbol} procedures:
2487    
2488  @rnindex string->symbol  @rnindex string->symbol
2489  @deffn {Scheme Procedure} string->symbol string  @deffn {Scheme Procedure} string->symbol string
2490  @deffnx {C Function} scm_string_to_symbol (string)  @deffnx {C Function} scm_string_to_symbol (string)
2491  Return the symbol whose name is @var{string}. This procedure  Return the symbol whose name is @var{string}.  This procedure can create
2492  can create symbols with names containing special characters or  symbols with names containing special characters or letters in the
2493  letters in the non-standard case, but it is usually a bad idea  non-standard case, but it is usually a bad idea to create such symbols
2494  to create such symbols because in some implementations of  because in some implementations of Scheme they cannot be read as
2495  Scheme they cannot be read as themselves.  See  themselves.
2496  @code{symbol->string}.  @end deffn
2497    
2498  The following examples assume that the implementation's  @deffn {Scheme Procedure} string-ci->symbol str
2499  standard case is lower case:  @deffnx {C Function} scm_string_ci_to_symbol (str)
2500    Return the symbol whose name is @var{str}.  If Guile is currently
2501    reading symbols case-insensitively, @var{str} is converted to lowercase
2502    before the returned symbol is looked up or created.
2503    @end deffn
2504    
2505    The following examples illustrate Guile's detailed behaviour as regards
2506    the case-sensitivity of symbols:
2507    
2508  @lisp  @lisp
2509  (eq? 'mISSISSIppi 'mississippi) @result{} #t  (read-enable 'case-insensitive)   ; R5RS compliant behaviour
2510  (string->symbol "mISSISSIppi") @result{} @r{the symbol with name "mISSISSIppi"}  
2511    (symbol->string 'flying-fish)    @result{} "flying-fish"
2512    (symbol->string 'Martin)         @result{} "martin"
2513    (symbol->string
2514       (string->symbol "Malvina"))   @result{} "Malvina"
2515    
2516    (eq? 'mISSISSIppi 'mississippi)  @result{} #t
2517    (string->symbol "mISSISSIppi")   @result{} mISSISSIppi
2518  (eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f  (eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f
2519  (eq? 'LolliPop  (eq? 'LolliPop
2520    (string->symbol (symbol->string 'LolliPop))) @result{} #t    (string->symbol (symbol->string 'LolliPop))) @result{} #t
2521  (string=? "K. Harper, M.D."  (string=? "K. Harper, M.D."
2522    (symbol->string    (symbol->string
2523      (string->symbol "K. Harper, M.D."))) @result{}#t      (string->symbol "K. Harper, M.D."))) @result{} #t
 @end lisp  
 @end deffn  
   
 @deffn {Scheme Procedure} string-ci->symbol str  
 @deffnx {C Function} scm_string_ci_to_symbol (str)  
 Return the symbol whose name is @var{str}.  @var{str} is  
 converted to lowercase before the conversion is done, if Guile  
 is currently reading symbols case-insensitively.  
 @end deffn  
2524    
2525  @rnindex symbol->string  (read-disable 'case-insensitive)   ; Guile default behaviour
 @deffn {Scheme Procedure} symbol->string s  
 @deffnx {C Function} scm_symbol_to_string (s)  
 Return the name of @var{symbol} as a string.  If the symbol was  
 part of an object returned as the value of a literal expression  
 (section @pxref{Literal expressions,,,r5rs, The Revised^5  
 Report on Scheme}) or by a call to the @code{read} procedure,  
 and its name contains alphabetic characters, then the string  
 returned will contain characters in the implementation's  
 preferred standard case---some implementations will prefer  
 upper case, others lower case.  If the symbol was returned by  
 @code{string->symbol}, the case of characters in the string  
 returned will be the same as the case in the string that was  
 passed to @code{string->symbol}.  It is an error to apply  
 mutation procedures like @code{string-set!} to strings returned  
 by this procedure.  
   
 The following examples assume that the implementation's  
 standard case is lower case:  
2526    
 @lisp  
2527  (symbol->string 'flying-fish)    @result{} "flying-fish"  (symbol->string 'flying-fish)    @result{} "flying-fish"
2528  (symbol->string 'Martin)         @result{}  "martin"  (symbol->string 'Martin)         @result{} "Martin"
2529  (symbol->string  (symbol->string
2530     (string->symbol "Malvina")) @result{} "Malvina"     (string->symbol "Malvina"))   @result{} "Malvina"
 @end lisp  
 @end deffn  
2531    
2532  @node Symbol Tables  (eq? 'mISSISSIppi 'mississippi)  @result{} #f
2533  @subsection Symbol Tables  (string->symbol "mISSISSIppi")   @result{} mISSISSIppi
2534    (eq? 'bitBlt (string->symbol "bitBlt")) @result{} #t
2535  @c FIXME::martin: Are all these procedures still relevant?  (eq? 'LolliPop
2536      (string->symbol (symbol->string 'LolliPop))) @result{} #t
2537    (string=? "K. Harper, M.D."
2538      (symbol->string
2539        (string->symbol "K. Harper, M.D."))) @result{} #t
2540    @end lisp
2541    
2542  Guile symbol tables are hash tables.  Each hash table, also called an  Finally, some applications, especially those that generate new Scheme
2543  @dfn{obarray} (for `object array'), is a vector of association lists.  code dynamically, need to generate symbols for use in the generated
2544  Each entry in the alists is a pair (@var{SYMBOL} . @var{VALUE}).  To  code.  The @code{gensym} primitive meets this need:
 @dfn{intern} a symbol in a symbol table means to return its  
 (@var{SYMBOL} . @var{VALUE}) pair, adding a new entry to the symbol  
 table (with an undefined value) if none is yet present.  
2545    
2546  @deffn {Scheme Procedure} gensym [prefix]  @deffn {Scheme Procedure} gensym [prefix]
2547  @deffnx {C Function} scm_gensym (prefix)  @deffnx {C Function} scm_gensym (prefix)
2548  Create a new symbol with a name constructed from a prefix and  Create a new symbol with a name constructed from a prefix and a counter
2549  a counter value. The string @var{prefix} can be specified as  value.  The string @var{prefix} can be specified as an optional
2550  an optional argument. Default prefix is @code{ g}.  The counter  argument.  Default prefix is @samp{ g}.  The counter is increased by 1
2551  is increased by 1 at each call. There is no provision for  at each call.  There is no provision for resetting the counter.
2552  resetting the counter.  @end deffn
2553  @end deffn  
2554    The symbols generated by @code{gensym} are @emph{likely} to be unique,
2555  @vgone{gentemp,1.6}  since their names begin with a space and it is only otherwise possible
2556  @vgone{intern-symbol,1.6}  to generate such symbols if a programmer goes out of their way to do
2557  @vgone{string->obarray-symbol,1.6}  so.  The 1.8 release of Guile will include a way of creating
2558  @vgone{symbol-binding,1.6}  symbols that are @emph{guaranteed} to be unique.
 @vgone{symbol-bound?,1.6}  
   
   
 @node Symbol Discrete  
 @subsection Using Symbols as Discrete Values  
   
 Symbols are especially useful because two symbols which are spelled the  
 same way are equivalent in the sense of @code{eq?}.  That means that  
 they are actually the same Scheme object.  The advantage is that symbols  
 can be compared extremely efficiently, although they carry more  
 information for the human reader than, say, numbers.  
   
 It is very common in Scheme programs to use symbols as keys in  
 association lists (@pxref{Association Lists}) or hash tables  
 (@pxref{Hash Tables}), because this usage improves the readability a  
 lot, and does not cause any performance loss.  
2559    
2560    
2561  @node Symbol Props  @node Symbol Props
2562  @subsection Function Slots and Property Lists  @subsection Function Slots and Property Lists
2563    
2564    In traditional Lisp dialects, symbols are often understood as having
2565    three kinds of value at once:
2566    
2567    @itemize @bullet
2568    @item
2569    a @dfn{variable} value, which is used when the symbol appears in
2570    code in a variable reference context
2571    
2572    @item
2573    a @dfn{function} value, which is used when the symbol appears in
2574    code in a function name position (i.e. as the first element in an
2575    unquoted list)
2576    
2577    @item
2578    a @dfn{property list} value, which is used when the symbol is given as
2579    the first argument to Lisp's @code{put} or @code{get} functions.
2580    @end itemize
2581    
2582    Although Scheme (as one of its simplifications with respect to Lisp)
2583    does away with the distinction between variable and function namespaces,
2584    Guile currently retains some elements of the traditional structure in
2585    case they turn out to be useful when implementing translators for other
2586    languages, in particular Emacs Lisp.
2587    
2588    Specifically, Guile symbols have two extra slots. for a symbol's
2589    property list, and for its ``function value.''  The following procedures
2590    are provided to access these slots.
2591    
2592  @deffn {Scheme Procedure} symbol-fref symbol  @deffn {Scheme Procedure} symbol-fref symbol
2593  @deffnx {C Function} scm_symbol_fref (symbol)  @deffnx {C Function} scm_symbol_fref (symbol)
2594  Return the contents of @var{symbol}'s @dfn{function slot}.  Return the contents of @var{symbol}'s @dfn{function slot}.
# Line 2457  Return the contents of @var{symbol}'s @d Line 2596  Return the contents of @var{symbol}'s @d
2596    
2597  @deffn {Scheme Procedure} symbol-fset! symbol value  @deffn {Scheme Procedure} symbol-fset! symbol value
2598  @deffnx {C Function} scm_symbol_fset_x (symbol, value)  @deffnx {C Function} scm_symbol_fset_x (symbol, value)
2599  Change the binding of @var{symbol}'s function slot.  Set the contents of @var{symbol}'s function slot to @var{value}.
 @end deffn  
   
 @deffn {Scheme Procedure} symbol-hash symbol  
 @deffnx {C Function} scm_symbol_hash (symbol)  
 Return a hash value for @var{symbol}.  
 @end deffn  
   
 @deffn {Scheme Procedure} symbol-interned? obarray string  
 @deffnx {C Function} scm_symbol_interned_p (obarray, string)  
 Return @code{#t} if @var{obarray} contains a symbol with name  
 @var{string}, and @code{#f} otherwise.  
2600  @end deffn  @end deffn
2601    
2602  @deffn {Scheme Procedure} symbol-pref symbol  @deffn {Scheme Procedure} symbol-pref symbol
# Line 2478  Return the @dfn{property list} currently Line 2606  Return the @dfn{property list} currently
2606    
2607  @deffn {Scheme Procedure} symbol-pset! symbol value  @deffn {Scheme Procedure} symbol-pset! symbol value
2608  @deffnx {C Function} scm_symbol_pset_x (symbol, value)  @deffnx {C Function} scm_symbol_pset_x (symbol, value)
2609  Change the binding of @var{symbol}'s property slot.  Set @var{symbol}'s property list to @var{value}.
2610  @end deffn  @end deffn
2611    
2612  @vgone{symbol-set!,1.6}  @deffn {Scheme Procedure} symbol-property sym prop
2613  @vgone{unintern-symbol,1.6}  From @var{sym}'s property list, return the value for property
2614    @var{prop}.  The assumption is that @var{sym}'s property list is an
2615    association list whose keys are distinguished from each other using
2616    @code{equal?}; @var{prop} should be one of the keys in that list.  If
2617    the property list has no entry for @var{prop}, @code{symbol-property}
2618    returns @code{#f}.
2619    @end deffn
2620    
2621    @deffn {Scheme Procedure} set-symbol-property sym prop val
2622    In @var{sym}'s property list, set the value for property @var{prop} to
2623    @var{val}, or add a new entry for @var{prop}, with value @var{val}, if
2624    none already exists.  For the structure of the property list, see
2625    @code{symbol-property}.
2626    @end deffn
2627    
2628    @deffn {Scheme Procedure} symbol-property-remove! sym prop
2629    From @var{sym}'s property list, remove the entry for property
2630    @var{prop}, if there is one.  For the structure of the property list,
2631    see @code{symbol-property}.
2632    @end deffn
2633    
2634    Support for these extra slots may be removed in a future release, and it
2635    is probably better to avoid using them.  (In release 1.6, Guile itself
2636    uses the property list slot sparingly, and the function slot not at
2637    all.)  For a more modern and Schemely approach to properties, see
2638    @ref{Object Properties}.
2639    
2640    
2641    @node Symbol Read Syntax
2642    @subsection Extended Read Syntax for Symbols
2643    
2644    The read syntax for a symbol is a sequence of letters, digits, and
2645    @dfn{extended alphabetic characters}, beginning with a character that
2646    cannot begin a number.  In addition, the special cases of @code{+},
2647    @code{-}, and @code{...} are read as symbols even though numbers can
2648    begin with @code{+}, @code{-} or @code{.}.
2649    
2650    Extended alphabetic characters may be used within identifiers as if
2651    they were letters.  The set of extended alphabetic characters is:
2652    
2653    @example
2654    ! $ % & * + - . / : < = > ? @@ ^ _ ~
2655    @end example
2656    
2657    In addition to the standard read syntax defined above (which is taken
2658    from R5RS (@pxref{Formal syntax,,,r5rs,The Revised^5 Report on
2659    Scheme})), Guile provides an extended symbol read syntax that allows the
2660    inclusion of unusual characters such as space characters, newlines and
2661    parentheses.  If (for whatever reason) you need to write a symbol
2662    containing characters not mentioned above, you can do so as follows.
2663    
2664    @itemize @bullet
2665    @item
2666    Begin the symbol with the characters @code{#@{},
2667    
2668    @item
2669    write the characters of the symbol and
2670    
2671    @item
2672    finish the symbol with the characters @code{@}#}.
2673    @end itemize
2674    
2675    Here are a few examples of this form of read syntax.  The first symbol
2676    needs to use extended syntax because it contains a space character, the
2677    second because it contains a line break, and the last because it looks
2678    like a number.
2679    
2680    @lisp
2681    #@{foo bar@}#
2682    
2683    #@{what
2684    ever@}#
2685    
2686    #@{4242@}#
2687    @end lisp
2688    
2689    Although Guile provides this extended read syntax for symbols,
2690    widespread usage of it is discouraged because it is not portable and not
2691    very readable.
2692    
2693    
2694  @node Symbol Uninterned  @node Symbol Uninterned
# Line 2491  Change the binding of @var{symbol}'s pro Line 2697  Change the binding of @var{symbol}'s pro
2697  What makes symbols useful is that they are automatically kept unique.  What makes symbols useful is that they are automatically kept unique.
2698  There are no two symbols that are distinct objects but have the same  There are no two symbols that are distinct objects but have the same
2699  name.  But of course, there is no rule without exception.  In addition  name.  But of course, there is no rule without exception.  In addition
2700  to the normal symbols that have been discussed upto now, you can also  to the normal symbols that have been discussed up to now, you can also
2701  create special @dfn{uninterned} symbols that behave slightly  create special @dfn{uninterned} symbols that behave slightly
2702  differently.  differently.
2703    
# Line 2551  For example: Line 2757  For example:
2757  (define foo-4 (make-symbol "foo"))  (define foo-4 (make-symbol "foo"))
2758    
2759  (eq? foo-1 foo-2)  (eq? foo-1 foo-2)
2760  @result{#t}  ; Two interned symbols with the same name are the same object,  @result{} #t
2761    ; Two interned symbols with the same name are the same object,
2762    
2763  (eq? foo-1 foo-3)  (eq? foo-1 foo-3)
2764  @result{#f}  ; but a call to make-symbol with the same name returns a  @result{} #f
2765               ; distinct object.  ; but a call to make-symbol with the same name returns a
2766    ; distinct object.
2767    
2768  (eq? foo-3 foo-4)  (eq? foo-3 foo-4)
2769  @result{#f}  ; A call to make-symbol always returns a new object, even for  @result{} #f
2770               ; the same name.  ; A call to make-symbol always returns a new object, even for
2771    ; the same name.
2772    
2773  foo-3  foo-3
2774  @result{#<uninterned-symbol foo 8085290>}  @result{} #<uninterned-symbol foo 8085290>
2775               ; Uninterned symbols print different from interned symbols,  ; Uninterned symbols print differently from interned symbols,
2776    
2777  (symbol? foo-3)  (symbol? foo-3)
2778  @result{#t}  ; but they are still symbols.  @result{} #t
2779    ; but they are still symbols,
2780    
2781  (symbol-interned? foo-3)  (symbol-interned? foo-3)
2782  @result{#f}  ; Just not interned.  @result{} #f
2783    ; just not interned.
2784  @end lisp  @end lisp
2785    
2786    

Legend:
Removed from v.1.16  
changed lines
  Added in v.1.17

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26