www.delorie.com/gnu/docs/guile/guile_205.html   search  
 
Buy GNU books!


Guile Reference Manual

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

21.6.4 Operations Related to Symbols

Given any Scheme value, you can determine whether it is a symbol using the symbol? primitive:

Scheme Procedure: symbol? obj
C Function: scm_symbol_p (obj)
Return #t if obj is a symbol, otherwise return #f.

Once you know that you have a symbol, you can obtain its name as a string by calling symbol->string. Note that Guile differs by default from R5RS on the details of symbol->string as regards case-sensitivity:

Scheme Procedure: symbol->string s
C Function: scm_symbol_to_string (s)
Return the name of symbol s as a string. By default, Guile reads symbols case-sensitively, so the string returned will have the same case variation as the sequence of characters that caused s to be created.

If Guile is set to read symbols case-insensitively (as specified by R5RS), and s comes into being as part of a literal expression (see section `Literal expressions' in The Revised^5 Report on Scheme) or by a call to the read or string-ci->symbol procedures, Guile converts any alphabetic characters in the symbol's name to lower case before creating the symbol object, so the string returned here will be in lower case.

If s was created by string->symbol, the case of characters in the string returned will be the same as that in the string that was passed to string->symbol, regardless of Guile's case-sensitivity setting at the time s was created.

It is an error to apply mutation procedures like string-set! to strings returned by this procedure.

Most symbols are created by writing them literally in code. However it is also possible to create symbols programmatically using the following string->symbol and string-ci->symbol procedures:

Scheme Procedure: string->symbol string
C Function: scm_string_to_symbol (string)
Return the symbol whose name is string. This procedure can create symbols with names containing special characters or letters in the non-standard case, but it is usually a bad idea to create such symbols because in some implementations of Scheme they cannot be read as themselves.

Scheme Procedure: string-ci->symbol str
C Function: scm_string_ci_to_symbol (str)
Return the symbol whose name is str. If Guile is currently reading symbols case-insensitively, str is converted to lowercase before the returned symbol is looked up or created.

The following examples illustrate Guile's detailed behaviour as regards the case-sensitivity of symbols:

 
(read-enable 'case-insensitive)   ; R5RS compliant behaviour

(symbol->string 'flying-fish)    => "flying-fish"
(symbol->string 'Martin)         => "martin"
(symbol->string
   (string->symbol "Malvina"))   => "Malvina"

(eq? 'mISSISSIppi 'mississippi)  => #t
(string->symbol "mISSISSIppi")   => mISSISSIppi
(eq? 'bitBlt (string->symbol "bitBlt")) => #f
(eq? 'LolliPop
  (string->symbol (symbol->string 'LolliPop))) => #t
(string=? "K. Harper, M.D."
  (symbol->string
    (string->symbol "K. Harper, M.D."))) => #t

(read-disable 'case-insensitive)   ; Guile default behaviour

(symbol->string 'flying-fish)    => "flying-fish"
(symbol->string 'Martin)         => "Martin"
(symbol->string
   (string->symbol "Malvina"))   => "Malvina"

(eq? 'mISSISSIppi 'mississippi)  => #f
(string->symbol "mISSISSIppi")   => mISSISSIppi
(eq? 'bitBlt (string->symbol "bitBlt")) => #t
(eq? 'LolliPop
  (string->symbol (symbol->string 'LolliPop))) => #t
(string=? "K. Harper, M.D."
  (symbol->string
    (string->symbol "K. Harper, M.D."))) => #t

Finally, some applications, especially those that generate new Scheme code dynamically, need to generate symbols for use in the generated code. The gensym primitive meets this need:

Scheme Procedure: gensym [prefix]
C Function: scm_gensym (prefix)
Create a new symbol with a name constructed from a prefix and a counter value. The string prefix can be specified as an optional argument. Default prefix is ` g'. The counter is increased by 1 at each call. There is no provision for resetting the counter.

The symbols generated by gensym are likely to be unique, since their names begin with a space and it is only otherwise possible to generate such symbols if a programmer goes out of their way to do so. The 1.8 release of Guile will include a way of creating symbols that are guaranteed to be unique.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

  webmaster     delorie software   privacy  
  Copyright 2003   by The Free Software Foundation     Updated Jun 2003