Next: , Previous: Symbol Variables, Up: Symbols

5.5.7.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.

— C Function: int scm_is_symbol (SCM val)

Equivalent to scm_is_true (scm_symbol_p (val)).

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 Literal expressions) 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

From C, there are lower level functions that construct a Scheme symbol from a C string in the current locale encoding.

When you want to do more from C, you should convert between symbols and strings using scm_symbol_to_string and scm_string_to_symbol and work with the strings.

— C Function: scm_from_locale_symbol (const char *name)
— C Function: scm_from_locale_symboln (const char *name, size_t len)

Construct and return a Scheme symbol whose name is specified by name. For scm_from_locale_symbol, name must be null terminated; for scm_from_locale_symboln the length of name is specified explicitly by len.

— C Function: SCM scm_take_locale_symbol (char *str)
— C Function: SCM scm_take_locale_symboln (char *str, size_t len)

Like scm_from_locale_symbol and scm_from_locale_symboln, respectively, but also frees str with free eventually. Thus, you can use this function when you would free str anyway immediately after creating the Scheme string. In certain cases, Guile can then use str directly as its internal representation.

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. Uniqueness can be guaranteed by instead using uninterned symbols (see Symbol Uninterned), though they can't be usefully written out and read back in.