Symbol Primitives (Guile Reference Manual)

Warning: This is the manual of the legacy Guile 2.2 series. You may want to read the manual of the current stable series instead.

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

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 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 procedures:

Scheme Procedure: symbol char…

Return a newly allocated symbol made from the given character arguments.

(symbol #\x #\y #\z) ⇒ xyz

Scheme Procedure: list->symbol lst

Return a newly allocated symbol made from a list of characters.

(list->symbol '(#\a #\b #\c)) ⇒ abc

Scheme Procedure: symbol-append arg …

Return a newly allocated symbol whose characters form the concatenation of the given symbols, arg ....

(let ((h 'hello))
  (symbol-append h 'world))
⇒ helloworld

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 scm_from_latin1_symbol (const char *name)
C Function: SCM scm_from_utf8_symbol (const char *name): Construct and return a Scheme symbol whose name is specified by the null-terminated C string name. These are appropriate when the C string is hard-coded in the source code.

C Function: SCM scm_from_locale_symbol (const char *name)

C Function: SCM 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.

Note that these functions should not be used when name is a C string constant, because there is no guarantee that the current locale will match that of the execution character set, used for string and character constants. Most modern C compilers use UTF-8 by default, so in such cases we recommend scm_from_utf8_symbol.

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.

The size of a symbol can also be obtained from C:

C Function: size_t scm_c_symbol_length (SCM sym): Return the number of characters in sym.

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.