www.delorie.com/gnu/docs/guile/guile_205.html

search

	Buy GNU books!

Guile Reference Manual

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.