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 |
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 |
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) |
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}. |
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 |
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 |
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 |
|
|
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 |
|
|