Simple Generic Data Types
*************************

This chapter describes those of Guile's simple data types which are primarily are used for their role as items of generic data.  By simple we mean data types that are not primarily used as containers to hold other data --- i.e. pairs, lists, vectors and so on. For the documentation of such compound data types, see Compound Data Types.

One of the great strengths of Scheme is that there is no straightforward distinction between ``data'' and ``functionality''.  For example, Guile's support for dynamic linking could be described

  * either in a ``data-centric'' way, as the behaviour and properties of the ``dynamically linked object'' data type, and the operations that may be applied to instances of this type

  * or in a ``functionality-centric'' way, as the set of procedures that constitute Guile's support for dynamic linking, in the context of the module system.

The contents of this chapter are, therefore, a matter of judgement.  By generic, we mean to select those data types whose typical use as data in a wide variety of programming contexts is more important than their use in the implementation of a particular piece of functionality.  The last section of this chapter provides references for all the data types that are documented not here but in a ``functionality-centric'' way elsewhere in the manual.

Booleans
========

The two boolean values are #t for true and #f for false.

Boolean values are returned by predicate procedures, such as the general equality predicates eq?, eqv? and equal? (see Equality) and numerical and string comparison operators like string=? (see String Comparison) and <= (see Comparison).

     (<= 3 8)
     =>
     #t

     (<= 3 -3)
     =>
     #f

     (equal? "house" "houses")
     =>
     #f

     (eq? #f #f)
     =>
     #t

In test condition contexts like if and cond (see if cond case), where a group of subexpressions will be evaluated only if a CONDITION expression evaluates to ``true'', ``true'' means any value at all except #f.

     (if #t "yes" "no")
     =>
     "yes"

     (if 0 "yes" "no")
     =>
     "yes"

     (if #f "yes" "no")
     =>
     "no"

A result of this asymmetry is that typical Scheme source code more often uses #f explicitly than #t: #f is necessary to represent an if or cond false value, whereas #t is not necessary to represent an if or cond true value.

It is important to note that #f is not equivalent to any other Scheme value.  In particular, #f is not the same as the number 0 (like in C and C++), and not the same as the ``empty list'' (like in some Lisp dialects).

The not procedure returns the boolean inverse of its argument:

 -- Scheme Procedure: not x
 -- C Function: scm_not (x)
     Return #t iff X is #f, else return #f.

The boolean? procedure is a predicate that returns #t if its argument is one of the boolean values, otherwise #f.

 -- Scheme Procedure: boolean? obj
 -- C Function: scm_boolean_p (obj)
     Return #t iff OBJ is either #t or #f.

Numerical data types
====================

Guile supports a rich ``tower'' of numerical types --- integer, rational, real and complex --- and provides an extensive set of mathematical and scientific functions for operating on numerical data.  This section of the manual documents those types and functions.

You may also find it illuminating to read R5RS's presentation of numbers in Scheme, which is particularly clear and accessible: see Numbers (r5rs).

Scheme's Numerical ``Tower''
----------------------------

Scheme's numerical ``tower'' consists of the following categories of numbers:

  * integers (whole numbers)

  * rationals (the set of numbers that can be expressed as P/Q where P and Q are integers)

  * real numbers (the set of numbers that describes all possible positions along a one dimensional line)

  * complex numbers (the set of numbers that describes all possible positions in a two dimensional space)

It is called a tower because each category ``sits on'' the one that follows it, in the sense that every integer is also a rational, every rational is also real, and every real number is also a complex number (but with zero imaginary part).

Of these, Guile implements integers, reals and complex numbers as distinct types.  Rationals are implemented as regards the read syntax for rational numbers that is specified by R5RS, but are immediately converted by Guile to the corresponding real number.

The number? predicate may be applied to any Scheme value to discover whether the value is any of the supported numerical types.

 -- Scheme Procedure: number? obj
 -- C Function: scm_number_p (obj)
     Return #t if OBJ is any kind of number, #f else.

For example:

     (number? 3)
     =>
     #t

     (number? "hello there!")
     =>
     #f

     (define pi 3.141592654)
     (number? pi)
     =>
     #t

The next few subsections document each of Guile's numerical data types in detail.

Integers
--------

Integers are whole numbers, that is numbers with no fractional part, such as 2, 83 and -3789.

Integers in Guile can be arbitrarily big, as shown by the following example.

     (define (factorial n)
       (let loop ((n n) (product 1))
         (if (= n 0)
             product
             (loop (- n 1) (* product n)))))

     (factorial 3)
     =>
     6

     (factorial 20)
     =>
     2432902008176640000

     (- (factorial 45))
     =>
     -119622220865480194561963161495657715064383733760000000000

Readers whose background is in programming languages where integers are limited by the need to fit into just 4 or 8 bytes of memory may find this surprising, or suspect that Guile's representation of integers is inefficient.  In fact, Guile achieves a near optimal balance of convenience and efficiency by using the host computer's native representation of integers where possible, and a more general representation where the required number does not fit in the native form.  Conversion between these two representations is automatic and completely invisible to the Scheme level programmer.

 -- Scheme Procedure: integer? x
 -- C Function: scm_integer_p (x)
     Return #t if X is an integer number, #f else.

          (integer? 487)
          =>
          #t

          (integer? -3.4)
          =>
          #f

Real and Rational Numbers
-------------------------

Mathematically, the real numbers are the set of numbers that describe all possible points along a continuous, infinite, one-dimensional line. The rational numbers are the set of all numbers that can be written as fractions P/Q, where P and Q are integers.  All rational numbers are also real, but there are real numbers that are not rational, for example the square root of 2, and pi.

Guile represents both real and rational numbers approximately using a floating point encoding with limited precision.  Even though the actual encoding is in binary, it may be helpful to think of it as a decimal number with a limited number of significant figures and a decimal point somewhere, since this corresponds to the standard notation for non-whole numbers.  For example:

     0.34
     -0.00000142857931198
     -5648394822220000000000.0
     4.0

The limited precision of Guile's encoding means that any ``real'' number in Guile can be written in a rational form, by multiplying and then dividing by sufficient powers of 10 (or in fact, 2).  For example, -0.00000142857931198 is the same as 142857931198 divided by 100000000000000000.  In Guile's current incarnation, therefore, the rational? and real? predicates are equivalent.

Another aspect of this equivalence is that Guile currently does not preserve the exactness that is possible with rational arithmetic. If such exactness is needed, it is of course possible to implement exact rational arithmetic at the Scheme level using Guile's arbitrary size integers.

A planned future revision of Guile's numerical tower will make it possible to implement exact representations and arithmetic for both rational numbers and real irrational numbers such as square roots, and in such a way that the new kinds of number integrate seamlessly with those that are already implemented.

 -- Scheme Procedure: real? obj
 -- C Function: scm_real_p (obj)
     Return #t if OBJ is a real number, #f else. Note that the sets of integer and rational values form subsets of the set of real numbers, so the predicate will also be fulfilled if OBJ is an integer number or a rational number.

 -- Scheme Procedure: rational? x
 -- C Function: scm_real_p (x)
     Return #t if X is a rational number, #f else.  Note that the set of integer values forms a subset of the set of rational numbers, i. e. the predicate will also be fulfilled if X is an integer number.  Real numbers will also satisfy this predicate, because of their limited precision.

Complex Numbers
---------------

Complex numbers are the set of numbers that describe all possible points in a two-dimensional space.  The two coordinates of a particular point in this space are known as the real and imaginary parts of the complex number that describes that point.

In Guile, complex numbers are written in rectangular form as the sum of their real and imaginary parts, using the symbol i to indicate the imaginary part.

     3+4i
     =>
     3.0+4.0i

     (* 3-8i 2.3+0.3i)
     =>
     9.3-17.5i

Guile represents a complex number as a pair of numbers both of which are real, so the real and imaginary parts of a complex number have the same properties of inexactness and limited precision as single real numbers.

 -- Scheme Procedure: complex? x
 -- C Function: scm_number_p (x)
     Return #t if X is a complex number, #f else.  Note that the sets of real, rational and integer values form subsets of the set of complex numbers, i. e. the predicate will also be fulfilled if X is a real, rational or integer number.

Exact and Inexact Numbers
-------------------------

R5RS requires that a calculation involving inexact numbers always produces an inexact result.  To meet this requirement, Guile distinguishes between an exact integer value such as 5 and the corresponding inexact real value which, to the limited precision available, has no fractional part, and is printed as 5.0.  Guile will only convert the latter value to the former when forced to do so by an invocation of the inexact->exact procedure.

 -- Scheme Procedure: exact? x
 -- C Function: scm_exact_p (x)
     Return #t if X is an exact number, #f otherwise.

 -- Scheme Procedure: inexact? x
 -- C Function: scm_inexact_p (x)
     Return #t if X is an inexact number, #f else.

 -- Scheme Procedure: inexact->exact z
 -- C Function: scm_inexact_to_exact (z)
     Return an exact number that is numerically closest to Z.

 -- Scheme Procedure: exact->inexact z
     Convert the number Z to its inexact representation.

Read Syntax for Numerical Data
------------------------------

The read syntax for integers is a string of digits, optionally preceded by a minus or plus character, a code indicating the base in which the integer is encoded, and a code indicating whether the number is exact or inexact.  The supported base codes are:

  * #b, #B --- the integer is written in binary (base 2)

  * #o, #O --- the integer is written in octal (base 8)

  * #d, #D --- the integer is written in decimal (base 10)

  * #x, #X --- the integer is written in hexadecimal (base 16).

If the base code is omitted, the integer is assumed to be decimal.  The following examples show how these base codes are used.

     -13
     =>
     -13

     #d-13
     =>
     -13

     #x-13
     =>
     -19

     #b+1101
     =>
     13

     #o377
     =>
     255

The codes for indicating exactness (which can, incidentally, be applied to all numerical values) are:

  * #e, #E --- the number is exact

  * #i, #I --- the number is inexact.

If the exactness indicator is omitted, the integer is assumed to be exact, since Guile's internal representation for integers is always exact. Real numbers have limited precision similar to the precision of the double type in C.  A consequence of the limited precision is that all real numbers in Guile are also rational, since any number R with a limited number of decimal places, say N, can be made into an integer by multiplying by 10^N.

Operations on Integer Values
----------------------------

 -- Scheme Procedure: odd? n
 -- C Function: scm_odd_p (n)
     Return #t if N is an odd number, #f otherwise.

 -- Scheme Procedure: even? n
 -- C Function: scm_even_p (n)
     Return #t if N is an even number, #f otherwise.

 -- Scheme Procedure: quotient
     Return the quotient of the numbers X and Y.

 -- Scheme Procedure: remainder
     Return the remainder of the numbers X and Y.

          (remainder 13 4) => 1
          (remainder -13 4) => -1

 -- Scheme Procedure: modulo
     Return the modulo of the numbers X and Y.

          (modulo 13 4) => 1
          (modulo -13 4) => 3

 -- Scheme Procedure: gcd
     Return the greatest common divisor of all arguments. If called without arguments, 0 is returned.

 -- Scheme Procedure: lcm
     Return the least common multiple of the arguments. If called without arguments, 1 is returned.

Comparison Predicates
---------------------

 -- Scheme Procedure: =
     Return #t if all parameters are numerically equal.

 -- Scheme Procedure: <
     Return #t if the list of parameters is monotonically increasing.

 -- Scheme Procedure: >
     Return #t if the list of parameters is monotonically decreasing.

 -- Scheme Procedure: <=
     Return #t if the list of parameters is monotonically non-decreasing.

 -- Scheme Procedure: >=
     Return #t if the list of parameters is monotonically non-increasing.

 -- Scheme Procedure: zero?
     Return #t if Z is an exact or inexact number equal to zero.

 -- Scheme Procedure: positive?
     Return #t if X is an exact or inexact number greater than zero.

 -- Scheme Procedure: negative?
     Return #t if X is an exact or inexact number less than zero.

Converting Numbers To and From Strings
--------------------------------------

 -- Scheme Procedure: number->string n [radix]
 -- C Function: scm_number_to_string (n, radix)
     Return a string holding the external representation of the number N in the given RADIX.  If N is inexact, a radix of 10 will be used.

 -- Scheme Procedure: string->number string [radix]
 -- C Function: scm_string_to_number (string, radix)
     Return a number of the maximally precise representation expressed by the given STRING. RADIX must be an exact integer, either 2, 8, 10, or 16. If supplied, RADIX is a default radix that may be overridden by an explicit radix prefix in STRING (e.g. "#o177"). If RADIX is not supplied, then the default radix is 10. If string is not a syntactically valid notation for a number, then string->number returns #f.

Complex Number Operations
-------------------------

 -- Scheme Procedure: make-rectangular real imaginary
 -- C Function: scm_make_rectangular (real, imaginary)
     Return a complex number constructed of the given REAL and IMAGINARY parts.

 -- Scheme Procedure: make-polar x y
 -- C Function: scm_make_polar (x, y)
     Return the complex number X * e^(i * Y).

 -- Scheme Procedure: real-part
     Return the real part of the number Z.

 -- Scheme Procedure: imag-part
     Return the imaginary part of the number Z.

 -- Scheme Procedure: magnitude
     Return the magnitude of the number Z. This is the same as abs for real arguments, but also allows complex numbers.

 -- Scheme Procedure: angle
     Return the angle of the complex number Z.

Arithmetic Functions
--------------------

 -- Scheme Procedure: + z1 ...
     Return the sum of all parameter values.  Return 0 if called without any parameters.

 -- Scheme Procedure: - z1 z2 ...
     If called with one argument Z1, -Z1 is returned. Otherwise the sum of all but the first argument are subtracted from the first argument.

 -- Scheme Procedure: * z1 ...
     Return the product of all arguments.  If called without arguments, 1 is returned.

 -- Scheme Procedure: / z1 z2 ...
     Divide the first argument by the product of the remaining arguments.  If called with one argument Z1, 1/Z1 is returned.

 -- Scheme Procedure: abs x
     Return the absolute value of X.

 -- Scheme Procedure: max x1 x2 ...
     Return the maximum of all parameter values.

 -- Scheme Procedure: min x1 x2 ...
     Return the minium of all parameter values.

 -- Scheme Procedure: truncate
     Round the inexact number X towards zero.

 -- Scheme Procedure: round x
     Round the inexact number X towards zero.

 -- Scheme Procedure: floor x
     Round the number X towards minus infinity.

 -- Scheme Procedure: ceiling x
     Round the number X towards infinity.

Scientific Functions
--------------------

The following procedures accept any kind of number as arguments, including complex numbers.

 -- Scheme Procedure: sqrt z
     Return the square root of Z.

 -- Scheme Procedure: expt z1 z2
     Return Z1 raised to the power of Z2.

 -- Scheme Procedure: sin z
     Return the sine of Z.

 -- Scheme Procedure: cos z
     Return the cosine of Z.

 -- Scheme Procedure: tan z
     Return the tangent of Z.

 -- Scheme Procedure: asin z
     Return the arcsine of Z.

 -- Scheme Procedure: acos z
     Return the arccosine of Z.

 -- Scheme Procedure: atan z
     Return the arctangent of Z.

 -- Scheme Procedure: exp z
     Return e to the power of Z, where e is the base of natural logarithms (2.71828...).

 -- Scheme Procedure: log z
     Return the natural logarithm of Z.

 -- Scheme Procedure: log10 z
     Return the base 10 logarithm of Z.

 -- Scheme Procedure: sinh z
     Return the hyperbolic sine of Z.

 -- Scheme Procedure: cosh z
     Return the hyperbolic cosine of Z.

 -- Scheme Procedure: tanh z
     Return the hyperbolic tangent of Z.

 -- Scheme Procedure: asinh z
     Return the hyperbolic arcsine of Z.

 -- Scheme Procedure: acosh z
     Return the hyperbolic arccosine of Z.

 -- Scheme Procedure: atanh z
     Return the hyperbolic arctangent of Z.

Primitive Numeric Functions
---------------------------

Many of Guile's numeric procedures which accept any kind of numbers as arguments, including complex numbers, are implemented as Scheme procedures that use the following real number-based primitives.  These primitives signal an error if they are called with complex arguments.

 -- Scheme Procedure: $abs x
     Return the absolute value of X.

 -- Scheme Procedure: $sqrt x
     Return the square root of X.

 -- Scheme Procedure: $expt x y
 -- C Function: scm_sys_expt (x, y)
     Return X raised to the power of Y. This procedure does not accept complex arguments.

 -- Scheme Procedure: $sin x
     Return the sine of X.

 -- Scheme Procedure: $cos x
     Return the cosine of X.

 -- Scheme Procedure: $tan x
     Return the tangent of X.

 -- Scheme Procedure: $asin x
     Return the arcsine of X.

 -- Scheme Procedure: $acos x
     Return the arccosine of X.

 -- Scheme Procedure: $atan x
     Return the arctangent of X in the range -PI/2 to PI/2.

 -- Scheme Procedure: $atan2 x y
 -- C Function: scm_sys_atan2 (x, y)
     Return the arc tangent of the two arguments X and Y. This is similar to calculating the arc tangent of X / Y, except that the signs of both arguments are used to determine the quadrant of the result. This procedure does not accept complex arguments.

 -- Scheme Procedure: $exp x
     Return e to the power of X, where e is the base of natural logarithms (2.71828...).

 -- Scheme Procedure: $log x
     Return the natural logarithm of X.

 -- Scheme Procedure: $sinh x
     Return the hyperbolic sine of X.

 -- Scheme Procedure: $cosh x
     Return the hyperbolic cosine of X.

 -- Scheme Procedure: $tanh x
     Return the hyperbolic tangent of X.

 -- Scheme Procedure: $asinh x
     Return the hyperbolic arcsine of X.

 -- Scheme Procedure: $acosh x
     Return the hyperbolic arccosine of X.

 -- Scheme Procedure: $atanh x
     Return the hyperbolic arctangent of X.

Bitwise Operations
------------------

 -- Scheme Procedure: logand n1 n2
     Return the bitwise AND of the integer arguments.

          (logand) => -1
          (logand 7) => 7
          (logand #b111 #b011 #b001) => 1

 -- Scheme Procedure: logior n1 n2
     Return the bitwise OR of the integer arguments.

          (logior) => 0
          (logior 7) => 7
          (logior #b000 #b001 #b011) => 3

 -- Scheme Procedure: logxor n1 n2
     Return the bitwise XOR of the integer arguments.  A bit is set in the result if it is set in an odd number of arguments.

          (logxor) => 0
          (logxor 7) => 7
          (logxor #b000 #b001 #b011) => 2
          (logxor #b000 #b001 #b011 #b011) => 1

 -- Scheme Procedure: lognot n
 -- C Function: scm_lognot (n)
     Return the integer which is the 2s-complement of the integer argument.

          (number->string (lognot #b10000000) 2)
             => "-10000001"
          (number->string (lognot #b0) 2)
             => "-1"

 -- Scheme Procedure: logtest j k
 -- C Function: scm_logtest (j, k)

          (logtest j k) == (not (zero? (logand j k)))

          (logtest #b0100 #b1011) => #f
          (logtest #b0100 #b0111) => #t

 -- Scheme Procedure: logbit? index j
 -- C Function: scm_logbit_p (index, j)

          (logbit? index j) == (logtest (integer-expt 2 index) j)

          (logbit? 0 #b1101) => #t
          (logbit? 1 #b1101) => #f
          (logbit? 2 #b1101) => #t
          (logbit? 3 #b1101) => #t
          (logbit? 4 #b1101) => #f

 -- Scheme Procedure: ash n cnt
 -- C Function: scm_ash (n, cnt)
     The function ash performs an arithmetic shift left by CNT bits (or shift right, if CNT is negative).  'Arithmetic' means, that the function does not guarantee to keep the bit structure of N, but rather guarantees that the result will always be rounded towards minus infinity.  Therefore, the results of ash and a corresponding bitwise shift will differ if N is negative.

     Formally, the function returns an integer equivalent to (inexact->exact (floor (* N (expt 2 CNT)))).

          (number->string (ash #b1 3) 2)     => "1000"
          (number->string (ash #b1010 -1) 2) => "101"

 -- Scheme Procedure: logcount n
 -- C Function: scm_logcount (n)
     Return the number of bits in integer N.  If integer is positive, the 1-bits in its binary representation are counted. If negative, the 0-bits in its two's-complement binary representation are counted.  If 0, 0 is returned.

          (logcount #b10101010)
             => 4
          (logcount 0)
             => 0
          (logcount -2)
             => 1

 -- Scheme Procedure: integer-length n
 -- C Function: scm_integer_length (n)
     Return the number of bits neccessary to represent N.

          (integer-length #b10101010)
             => 8
          (integer-length 0)
             => 0
          (integer-length #b1111)
             => 4

 -- Scheme Procedure: integer-expt n k
 -- C Function: scm_integer_expt (n, k)
     Return N raised to the non-negative integer exponent K.

          (integer-expt 2 5)
             => 32
          (integer-expt -3 3)
             => -27

 -- Scheme Procedure: bit-extract n start end
 -- C Function: scm_bit_extract (n, start, end)
     Return the integer composed of the START (inclusive) through END (exclusive) bits of N.  The STARTth bit becomes the 0-th bit in the result.

          (number->string (bit-extract #b1101101010 0 4) 2)
             => "1010"
          (number->string (bit-extract #b1101101010 4 9) 2)
             => "10110"

Random Number Generation
------------------------

 -- Scheme Procedure: copy-random-state [state]
 -- C Function: scm_copy_random_state (state)
     Return a copy of the random state STATE.

 -- Scheme Procedure: random n [state]
 -- C Function: scm_random (n, state)
     Return a number in [0,N).

     Accepts a positive integer or real n and returns a number of the same type between zero (inclusive) and N (exclusive). The values returned have a uniform distribution.

     The optional argument STATE must be of the type produced by seed->random-state. It defaults to the value of the variable *RANDOM-STATE*. This object is used to maintain the state of the pseudo-random-number generator and is altered as a side effect of the random operation.

 -- Scheme Procedure: random:exp [state]
 -- C Function: scm_random_exp (state)
     Return an inexact real in an exponential distribution with mean 1.  For an exponential distribution with mean u use (* u (random:exp)).

 -- Scheme Procedure: random:hollow-sphere! v [state]
 -- C Function: scm_random_hollow_sphere_x (v, state)
     Fills vect with inexact real random numbers the sum of whose squares is equal to 1.0. Thinking of vect as coordinates in space of dimension n = (vector-length vect), the coordinates are uniformly distributed over the surface of the unit n-sphere.

 -- Scheme Procedure: random:normal [state]
 -- C Function: scm_random_normal (state)
     Return an inexact real in a normal distribution.  The distribution used has mean 0 and standard deviation 1.  For a normal distribution with mean m and standard deviation d use (+ m (* d (random:normal))).

 -- Scheme Procedure: random:normal-vector! v [state]
 -- C Function: scm_random_normal_vector_x (v, state)
     Fills vect with inexact real random numbers that are independent and standard normally distributed (i.e., with mean 0 and variance 1).

 -- Scheme Procedure: random:solid-sphere! v [state]
 -- C Function: scm_random_solid_sphere_x (v, state)
     Fills vect with inexact real random numbers the sum of whose squares is less than 1.0. Thinking of vect as coordinates in space of dimension n = (vector-length vect), the coordinates are uniformly distributed within the unit n-sphere. The sum of the squares of the numbers is returned.

 -- Scheme Procedure: random:uniform [state]
 -- C Function: scm_random_uniform (state)
     Return a uniformly distributed inexact real random number in [0,1).

 -- Scheme Procedure: seed->random-state seed
 -- C Function: scm_seed_to_random_state (seed)
     Return a new random state using SEED.

Characters
==========

Most of the characters in the ASCII character set may be referred to by name: for example, #\tab, #\esc, #\stx, and so on. The following table describes the ASCII names for each character.

0 = #\nul
1 = #\soh
2 = #\stx
3 = #\etx
4 = #\eot
5 = #\enq
6 = #\ack
7 = #\bel
8 = #\bs
9 = #\ht
10 = #\nl
11 = #\vt
12 = #\np
13 = #\cr
14 = #\so
15 = #\si
16 = #\dle
17 = #\dc1
18 = #\dc2
19 = #\dc3
20 = #\dc4
21 = #\nak
22 = #\syn
23 = #\etb
24 = #\can
25 = #\em
26 = #\sub
27 = #\esc
28 = #\fs
29 = #\gs
30 = #\rs
31 = #\us
32 = #\sp

The delete character (octal 177) may be referred to with the name #\del.

Several characters have more than one name:

  * #\space, #\sp

  * #\newline, #\nl

  * #\tab, #\ht

  * #\backspace, #\bs

  * #\return, #\cr

  * #\page, #\np

  * #\null, #\nul

 -- Scheme Procedure: char? x
 -- C Function: scm_char_p (x)
     Return #t iff X is a character, else #f.

 -- Scheme Procedure: char=? x y
     Return #t iff X is the same character as Y, else #f.

 -- Scheme Procedure: char<? x y
     Return #t iff X is less than Y in the ASCII sequence, else #f.

 -- Scheme Procedure: char<=? x y
     Return #t iff X is less than or equal to Y in the ASCII sequence, else #f.

 -- Scheme Procedure: char>? x y
     Return #t iff X is greater than Y in the ASCII sequence, else #f.

 -- Scheme Procedure: char>=? x y
     Return #t iff X is greater than or equal to Y in the ASCII sequence, else #f.

 -- Scheme Procedure: char-ci=? x y
     Return #t iff X is the same character as Y ignoring case, else #f.

 -- Scheme Procedure: char-ci<? x y
     Return #t iff X is less than Y in the ASCII sequence ignoring case, else #f.

 -- Scheme Procedure: char-ci<=? x y
     Return #t iff X is less than or equal to Y in the ASCII sequence ignoring case, else #f.

 -- Scheme Procedure: char-ci>? x y
     Return #t iff X is greater than Y in the ASCII sequence ignoring case, else #f.

 -- Scheme Procedure: char-ci>=? x y
     Return #t iff X is greater than or equal to Y in the ASCII sequence ignoring case, else #f.

 -- Scheme Procedure: char-alphabetic? chr
 -- C Function: scm_char_alphabetic_p (chr)
     Return #t iff CHR is alphabetic, else #f. Alphabetic means the same thing as the isalpha C library function.

 -- Scheme Procedure: char-numeric? chr
 -- C Function: scm_char_numeric_p (chr)
     Return #t iff CHR is numeric, else #f. Numeric means the same thing as the isdigit C library function.

 -- Scheme Procedure: char-whitespace? chr
 -- C Function: scm_char_whitespace_p (chr)
     Return #t iff CHR is whitespace, else #f. Whitespace means the same thing as the isspace C library function.

 -- Scheme Procedure: char-upper-case? chr
 -- C Function: scm_char_upper_case_p (chr)
     Return #t iff CHR is uppercase, else #f. Uppercase means the same thing as the isupper C library function.

 -- Scheme Procedure: char-lower-case? chr
 -- C Function: scm_char_lower_case_p (chr)
     Return #t iff CHR is lowercase, else #f. Lowercase means the same thing as the islower C library function.

 -- Scheme Procedure: char-is-both? chr
 -- C Function: scm_char_is_both_p (chr)
     Return #t iff CHR is either uppercase or lowercase, else #f. Uppercase and lowercase are as defined by the isupper and islower C library functions.

 -- Scheme Procedure: char->integer chr
 -- C Function: scm_char_to_integer (chr)
     Return the number corresponding to ordinal position of CHR in the ASCII sequence.

 -- Scheme Procedure: integer->char n
 -- C Function: scm_integer_to_char (n)
     Return the character at position N in the ASCII sequence.

 -- Scheme Procedure: char-upcase chr
 -- C Function: scm_char_upcase (chr)
     Return the uppercase character version of CHR.

 -- Scheme Procedure: char-downcase chr
 -- C Function: scm_char_downcase (chr)
     Return the lowercase character version of CHR.

Strings
=======

Strings are fixed-length sequences of characters.  They can be created by calling constructor procedures, but they can also literally get entered at the REPL or in Scheme source files.

Guile provides a rich set of string processing procedures, because text handling is very important when Guile is used as a scripting language.

Strings always carry the information about how many characters they are composed of with them, so there is no special end-of-string character, like in C.  That means that Scheme strings can contain any character, even the NUL character '\0'.  But note: Since most operating system calls dealing with strings (such as for file operations) expect strings to be zero-terminated, they might do unexpected things when called with string containing unusal characters.

String Read Syntax
------------------

The read syntax for strings is an arbitrarily long sequence of characters enclosed in double quotes (").  (Actually, the current implementation restricts strings to a length of 2^24 characters.)  If you want to insert a double quote character into a string literal, it must be prefixed with a backslash \ character (called an escape character).

The following are examples of string literals:

     "foo"
     "bar plonk"
     "Hello World"
     "\"Hi\", he said."

String Predicates
-----------------

The following procedures can be used to check whether a given string fulfills some specified property.

 -- Scheme Procedure: string? obj
 -- C Function: scm_string_p (obj)
     Return #t iff OBJ is a string, else #f.

 -- Scheme Procedure: string-null? str
 -- C Function: scm_string_null_p (str)
     Return #t if STR's length is zero, and #f otherwise.

          (string-null? "")  => #t
          y                    => "foo"
          (string-null? y)     => #f

String Constructors
-------------------

The string constructor procedures create new string objects, possibly initializing them with some specified character data.

 -- Scheme Procedure: string . chrs
 -- Scheme Procedure: list->string chrs
 -- C Function: scm_string (chrs)
     Return a newly allocated string composed of the arguments, CHRS.

 -- Scheme Procedure: make-string k [chr]
 -- C Function: scm_make_string (k, chr)
     Return a newly allocated string of length K.  If CHR is given, then all elements of the string are initialized to CHR, otherwise the contents of the STRING are unspecified.

List/String conversion
----------------------

When processing strings, it is often convenient to first convert them into a list representation by using the procedure string->list, work with the resulting list, and then convert it back into a string. These procedures are useful for similar tasks.

 -- Scheme Procedure: string->list str
 -- C Function: scm_string_to_list (str)
     Return a newly allocated list of the characters that make up the given string STR. string->list and list->string are inverses as far as equal? is concerned.

 -- Scheme Procedure: string-split str chr
 -- C Function: scm_string_split (str, chr)
     Split the string STR into the a list of the substrings delimited by appearances of the character CHR.  Note that an empty substring between separator characters will result in an empty string in the result list.

          (string-split "root:x:0:0:root:/root:/bin/bash" #\:)
          =>
          ("root" "x" "0" "0" "root" "/root" "/bin/bash")

          (string-split "::" #\:)
          =>
          ("" "" "")

          (string-split "" #\:)
          =>
          ("")

String Selection
----------------

Portions of strings can be extracted by these procedures. string-ref delivers individual characters whereas substring can be used to extract substrings from longer strings.

 -- Scheme Procedure: string-length string
 -- C Function: scm_string_length (string)
     Return the number of characters in STRING.

 -- Scheme Procedure: string-ref str k
 -- C Function: scm_string_ref (str, k)
     Return character K of STR using zero-origin indexing. K must be a valid index of STR.

 -- Scheme Procedure: string-copy str
 -- C Function: scm_string_copy (str)
     Return a newly allocated copy of the given STRING.

 -- Scheme Procedure: substring str start [end]
 -- C Function: scm_substring (str, start, end)
     Return a newly allocated string formed from the characters of STR beginning with index START (inclusive) and ending with index END (exclusive). STR must be a string, START and END must be exact integers satisfying:

     0 <= START <= END <= (string-length STR).

String Modification
-------------------

These procedures are for modifying strings in-place.  This means that the result of the operation is not a new string; instead, the original string's memory representation is modified.

 -- Scheme Procedure: string-set! str k chr
 -- C Function: scm_string_set_x (str, k, chr)
     Store CHR in element K of STR and return an unspecified value. K must be a valid index of STR.

 -- Scheme Procedure: string-fill! str chr
 -- C Function: scm_string_fill_x (str, chr)
     Store CHAR in every element of the given STRING and return an unspecified value.

 -- Scheme Procedure: substring-fill! str start end fill
 -- C Function: scm_substring_fill_x (str, start, end, fill)
     Change every character in STR between START and END to FILL.

          (define y "abcdefg")
          (substring-fill! y 1 3 #\r)
          y
          => "arrdefg"

 -- Scheme Procedure: substring-move! str1 start1 end1 str2 start2
 -- C Function: scm_substring_move_x (str1, start1, end1, str2, start2)
     Copy the substring of STR1 bounded by START1 and END1 into STR2 beginning at position START2. STR1 and STR2 can be the same string.

String Comparison
-----------------

The procedures in this section are similar to the character ordering predicates (see Characters), but are defined on character sequences. They all return #t on success and #f on failure.  The predicates ending in -ci ignore the character case when comparing strings.

 -- Scheme Procedure: string=? s1 s2
     Lexicographic equality predicate; return #t if the two strings are the same length and contain the same characters in the same positions, otherwise return #f.

     The procedure string-ci=? treats upper and lower case letters as though they were the same character, but string=? treats upper and lower case as distinct characters.

 -- Scheme Procedure: string<? s1 s2
     Lexicographic ordering predicate; return #t if S1 is lexicographically less than S2.

 -- Scheme Procedure: string<=? s1 s2
     Lexicographic ordering predicate; return #t if S1 is lexicographically less than or equal to S2.

 -- Scheme Procedure: string>? s1 s2
     Lexicographic ordering predicate; return #t if S1 is lexicographically greater than S2.

 -- Scheme Procedure: string>=? s1 s2
     Lexicographic ordering predicate; return #t if S1 is lexicographically greater than or equal to S2.

 -- Scheme Procedure: string-ci=? s1 s2
     Case-insensitive string equality predicate; return #t if the two strings are the same length and their component characters match (ignoring case) at each position; otherwise return #f.

 -- Scheme Procedure: string-ci<? s1 s2
     Case insensitive lexicographic ordering predicate; return #t if S1 is lexicographically less than S2 regardless of case.

 -- Scheme Procedure: string-ci<=? s1 s2
     Case insensitive lexicographic ordering predicate; return #t if S1 is lexicographically less than or equal to S2 regardless of case.

 -- Scheme Procedure: string-ci>? s1 s2
     Case insensitive lexicographic ordering predicate; return #t if S1 is lexicographically greater than S2 regardless of case.

 -- Scheme Procedure: string-ci>=? s1 s2
     Case insensitive lexicographic ordering predicate; return #t if S1 is lexicographically greater than or equal to S2 regardless of case.

String Searching
----------------

When searching for the index of a character in a string, these procedures can be used.

 -- Scheme Procedure: string-index str chr [frm [to]]
 -- C Function: scm_string_index (str, chr, frm, to)
     Return the index of the first occurrence of CHR in STR.  The optional integer arguments FRM and TO limit the search to a portion of the string.  This procedure essentially implements the index or strchr functions from the C library.

          (string-index "weiner" #\e)
          => 1

          (string-index "weiner" #\e 2)
          => 4

          (string-index "weiner" #\e 2 4)
          => #f

 -- Scheme Procedure: string-rindex str chr [frm [to]]
 -- C Function: scm_string_rindex (str, chr, frm, to)
     Like string-index, but search from the right of the string rather than from the left.  This procedure essentially implements the rindex or strrchr functions from the C library.

          (string-rindex "weiner" #\e)
          => 4

          (string-rindex "weiner" #\e 2 4)
          => #f

          (string-rindex "weiner" #\e 2 5)
          => 4

Alphabetic Case Mapping
-----------------------

These are procedures for mapping strings to their upper- or lower-case equivalents, respectively, or for capitalizing strings.

 -- Scheme Procedure: string-upcase str
 -- C Function: scm_string_upcase (str)
     Return a freshly allocated string containing the characters of STR in upper case.

 -- Scheme Procedure: string-upcase! str
 -- C Function: scm_string_upcase_x (str)
     Destructively upcase every character in STR and return STR.

          y                  => "arrdefg"
          (string-upcase! y) => "ARRDEFG"
          y                  => "ARRDEFG"

 -- Scheme Procedure: string-downcase str
 -- C Function: scm_string_downcase (str)
     Return a freshly allocation string containing the characters in STR in lower case.

 -- Scheme Procedure: string-downcase! str
 -- C Function: scm_string_downcase_x (str)
     Destructively downcase every character in STR and return STR.

          y                     => "ARRDEFG"
          (string-downcase! y)  => "arrdefg"
          y                     => "arrdefg"

 -- Scheme Procedure: string-capitalize str
 -- C Function: scm_string_capitalize (str)
     Return a freshly allocated string with the characters in STR, where the first character of every word is capitalized.

 -- Scheme Procedure: string-capitalize! str
 -- C Function: scm_string_capitalize_x (str)
     Upcase the first character of every word in STR destructively and return STR.

          y                      => "hello world"
          (string-capitalize! y) => "Hello World"
          y                      => "Hello World"

Appending Strings
-----------------

The procedure string-append appends several strings together to form a longer result string.

 -- Scheme Procedure: string-append . args
 -- C Function: scm_string_append (args)
     Return a newly allocated string whose characters form the concatenation of the given strings, ARGS.

Regular Expressions
===================

A regular expression (or regexp) is a pattern that describes a whole class of strings.  A full description of regular expressions and their syntax is beyond the scope of this manual; an introduction can be found in the Emacs manual (see Syntax of Regular Expressions (The GNU Emacs Manual)), or in many general Unix reference books.

If your system does not include a POSIX regular expression library, and you have not linked Guile with a third-party regexp library such as Rx, these functions will not be available.  You can tell whether your Guile installation includes regular expression support by checking whether the *features* list includes the regex symbol.

[FIXME: it may be useful to include an Examples section.  Parts of this interface are bewildering on first glance.]

Regexp Functions
----------------

By default, Guile supports POSIX extended regular expressions. That means that the characters (, ), + and ? are special, and must be escaped if you wish to match the literal characters.

This regular expression interface was modeled after that implemented by SCSH, the Scheme Shell.  It is intended to be upwardly compatible with SCSH regular expressions.

 -- Scheme Procedure: string-match pattern str [start]
     Compile the string PATTERN into a regular expression and compare it with STR.  The optional numeric argument START specifies the position of STR at which to begin matching.

     string-match returns a match structure which describes what, if anything, was matched by the regular expression.  See Match Structures.  If STR does not match PATTERN at all, string-match returns #f.

Each time string-match is called, it must compile its PATTERN argument into a regular expression structure.  This operation is expensive, which makes string-match inefficient if the same regular expression is used several times (for example, in a loop).  For better performance, you can compile a regular expression in advance and then match strings against the compiled regexp.

 -- Scheme Procedure: make-regexp pat . flags
 -- C Function: scm_make_regexp (pat, flags)
     Compile the regular expression described by PAT, and return the compiled regexp structure.  If PAT does not describe a legal regular expression, make-regexp throws a regular-expression-syntax error.

     The FLAGS arguments change the behavior of the compiled regular expression.  The following flags may be supplied:

     regexp/icase
          Consider uppercase and lowercase letters to be the same when matching.

     regexp/newline
          If a newline appears in the target string, then permit the ^ and $ operators to match immediately after or immediately before the newline, respectively.  Also, the . and [^...] operators will never match a newline character.  The intent of this flag is to treat the target string as a buffer containing many lines of text, and the regular expression as a pattern that may match a single one of those lines.

     regexp/basic
          Compile a basic (``obsolete'') regexp instead of the extended (``modern'') regexps that are the default.  Basic regexps do not consider |, + or ? to be special characters, and require the {...} and (...) metacharacters to be backslash-escaped (see Backslash Escapes).  There are several other differences between basic and extended regular expressions, but these are the most significant.

     regexp/extended
          Compile an extended regular expression rather than a basic regexp.  This is the default behavior; this flag will not usually be needed.  If a call to make-regexp includes both regexp/basic and regexp/extended flags, the one which comes last will override the earlier one.

 -- Scheme Procedure: regexp-exec rx str [start [flags]]
 -- C Function: scm_regexp_exec (rx, str, start, flags)
     Match the compiled regular expression RX against str.  If the optional integer START argument is provided, begin matching from that position in the string. Return a match structure describing the results of the match, or #f if no match could be found.

     The FLAGS arguments change the matching behavior. The following flags may be supplied:

     regexp/notbol
          Operator ^ always fails (unless regexp/newline is used).  Use this when the beginning of the string should not be considered the beginning of a line.

     regexp/noteol
          Operator $ always fails (unless regexp/newline is used).  Use this when the end of the string should not be considered the end of a line.

 -- Scheme Procedure: regexp? obj
 -- C Function: scm_regexp_p (obj)
     Return #t if OBJ is a compiled regular expression, or #f otherwise.

Regular expressions are commonly used to find patterns in one string and replace them with the contents of another string.

 -- Scheme Procedure: regexp-substitute port match [item...]
     Write to the output port PORT selected contents of the match structure MATCH.  Each ITEM specifies what should be written, and may be one of the following arguments:

       * A string.  String arguments are written out verbatim.

       * An integer.  The submatch with that number is written.

       * The symbol pre.  The portion of the matched string preceding the regexp match is written.

       * The symbol post.  The portion of the matched string following the regexp match is written.

     PORT may be #f, in which case nothing is written; instead, regexp-substitute constructs a string from the specified ITEMs and returns that.

 -- Scheme Procedure: regexp-substitute/global port regexp target [item...]
     Similar to regexp-substitute, but can be used to perform global substitutions on STR.  Instead of taking a match structure as an argument, regexp-substitute/global takes two string arguments: a REGEXP string describing a regular expression, and a TARGET string which should be matched against this regular expression.

     Each ITEM behaves as in REGEXP-SUBSTITUTE, with the following exceptions:

       * A function may be supplied.  When this function is called, it will be passed one argument: a match structure for a given regular expression match.  It should return a string to be written out to PORT.

       * The post symbol causes regexp-substitute/global to recurse on the unmatched portion of STR.  This must be supplied in order to perform global search-and-replace on STR; if it is not present among the ITEMs, then regexp-substitute/global will return after processing a single match.

Match Structures
----------------

A match structure is the object returned by string-match and regexp-exec.  It describes which portion of a string, if any, matched the given regular expression.  Match structures include: a reference to the string that was checked for matches; the starting and ending positions of the regexp match; and, if the regexp included any parenthesized subexpressions, the starting and ending positions of each submatch.

In each of the regexp match functions described below, the match argument must be a match structure returned by a previous call to string-match or regexp-exec.  Most of these functions return some information about the original target string that was matched against a regular expression; we will call that string TARGET for easy reference.

 -- Scheme Procedure: regexp-match? obj
     Return #t if OBJ is a match structure returned by a previous call to regexp-exec, or #f otherwise.

 -- Scheme Procedure: match:substring match [n]
     Return the portion of TARGET matched by subexpression number N.  Submatch 0 (the default) represents the entire regexp match. If the regular expression as a whole matched, but the subexpression number N did not match, return #f.

 -- Scheme Procedure: match:start match [n]
     Return the starting position of submatch number N.

 -- Scheme Procedure: match:end match [n]
     Return the ending position of submatch number N.

 -- Scheme Procedure: match:prefix match
     Return the unmatched portion of TARGET preceding the regexp match.

 -- Scheme Procedure: match:suffix match
     Return the unmatched portion of TARGET following the regexp match.

 -- Scheme Procedure: match:count match
     Return the number of parenthesized subexpressions from MATCH. Note that the entire regular expression match itself counts as a subexpression, and failed submatches are included in the count.

 -- Scheme Procedure: match:string match
     Return the original TARGET string.

Backslash Escapes
-----------------

Sometimes you will want a regexp to match characters like * or $ exactly.  For example, to check whether a particular string represents a menu entry from an Info node, it would be useful to match it against a regexp like ^* [^:]*::.  However, this won't work; because the asterisk is a metacharacter, it won't match the * at the beginning of the string.  In this case, we want to make the first asterisk un-magic.

You can do this by preceding the metacharacter with a backslash character \.  (This is also called quoting the metacharacter, and is known as a backslash escape.)  When Guile sees a backslash in a regular expression, it considers the following glyph to be an ordinary character, no matter what special meaning it would ordinarily have.  Therefore, we can make the above example work by changing the regexp to ^\* [^:]*::.  The \* sequence tells the regular expression engine to match only a single asterisk in the target string.

Since the backslash is itself a metacharacter, you may force a regexp to match a backslash in the target string by preceding the backslash with itself.  For example, to find variable references in a TeX program, you might want to find occurrences of the string \let\ followed by any number of alphabetic characters.  The regular expression \\let\\[A-Za-z]* would do this: the double backslashes in the regexp each match a single backslash in the target string.

 -- Scheme Procedure: regexp-quote str
     Quote each special character found in STR with a backslash, and return the resulting string.

Very important: Using backslash escapes in Guile source code (as in Emacs Lisp or C) can be tricky, because the backslash character has special meaning for the Guile reader.  For example, if Guile encounters the character sequence \n in the middle of a string while processing Scheme code, it replaces those characters with a newline character.  Similarly, the character sequence \t is replaced by a horizontal tab.  Several of these escape sequences are processed by the Guile reader before your code is executed. Unrecognized escape sequences are ignored: if the characters \* appear in a string, they will be translated to the single character *.

This translation is obviously undesirable for regular expressions, since we want to be able to include backslashes in a string in order to escape regexp metacharacters.  Therefore, to make sure that a backslash is preserved in a string in your Guile program, you must use two consecutive backslashes:

     (define Info-menu-entry-pattern (make-regexp "^\\* [^:]*"))

The string in this example is preprocessed by the Guile reader before any code is executed.  The resulting argument to make-regexp is the string ^\* [^:]*, which is what we really want.

This also means that in order to write a regular expression that matches a single backslash character, the regular expression string in the source code must include four backslashes.  Each consecutive pair of backslashes gets translated by the Guile reader to a single backslash, and the resulting double-backslash is interpreted by the regexp engine as matching a single backslash character.  Hence:

     (define tex-variable-pattern (make-regexp "\\\\let\\\\=[A-Za-z]*"))

The reason for the unwieldiness of this syntax is historical.  Both regular expression pattern matchers and Unix string processing systems have traditionally used backslashes with the special meanings described above.  The POSIX regular expression specification and ANSI C standard both require these semantics.  Attempting to abandon either convention would cause other kinds of compatibility problems, possibly more severe ones.  Therefore, without extending the Scheme reader to support strings with different quoting conventions (an ungainly and confusing extension when implemented in other languages), we must adhere to this cumbersome escape syntax.

Symbols
=======

Symbols have two main uses.  Crucially, they are used for denoting variables in a Scheme program.  In addition, they are very useful for describing discrete literal data.

A symbol is an object with a name that consists of a string of characters.  In the usual case (where the name doesn't include any characters that could be confused with other elements of Scheme syntax) a symbol can be written in a Scheme program by writing the sequence of characters that make up the symbol's name.  For example, the read syntax for the symbol named "multiply-by-2" is simply

     multiply-by-2

Symbols, then, look rather like strings but without any quotation marks. But there are several functional differences between them.  The first big functional difference between symbols and strings concerns uniqueness.  If the same-looking string is read twice from two different places in a program, the result is two 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 same symbol object both times.

     (define str1 "hello")
     (define str2 "hello")
     (eq? str1 str2) => #f

     (define sym1 (quote hello))
     (define sym2 (quote hello))
     (eq? sym1 sym2) => #t

The second important difference is that symbols, unlike strings, are not self-evaluating.  An unquoted symbol is interpreted as a variable reference, and the result of evaluating that symbol is the corresponding variable's value.  (By the way, this is why we needed the (quote ...)s in the example above: (quote hello) returns the symbol object named "hello" itself, whereas an unquoted hello would try to find and dereference a variable associated with that symbol.)

For example, when the expression (string-length "abcd") is read and evaluated, the sequence of characters 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 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 Binding Constructs, for how associations between symbols and variables are created, and 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 per se.

Extended Read Syntax for Symbols
--------------------------------

The read syntax for symbols is a sequence of letters, digits, and extended alphabetic characters, beginning with a character that cannot begin a number.  In addition, the special cases of +, -, and ... are read as symbols even though numbers can begin with +, - or ..

Extended alphabetic characters may be used within identifiers as if they were letters.  The set of extended alphabetic characters is:

     ! $ % & * + - . / : < = > ? @ ^ _ ~

In addition to the standard read syntax defined above (which is taken from R5RS (see Formal syntax (The Revised^5 Report on Scheme))), Guile provides an extended symbol read syntax that allows the inclusion of unusual characters such as space characters, newlines and parentheses.  If (for whatever reason) you need to write a symbol containing characters not mentioned above, you can do so as follows.

  * Begin the symbol with the characters #{,

  * write the characters of the symbol and

  * finish the symbol with the characters }#.

Here are a few examples of this form of read syntax.  The first symbol needs to use extended syntax because it contains a space character, the second because it contains a line break, and the last because it looks like a number.

     #{foo bar}#

     #{what
     ever}#

     #{4242}#

Although Guile provides this extended read syntax for symbols, widespread usage of it is discouraged because it is not portable and not very readable.

Operations Related to Symbols
-----------------------------

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

 -- 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.  See symbol->string.

     The following examples assume that the implementation's standard case is lower case:

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

 -- Scheme Procedure: string-ci->symbol str
 -- C Function: scm_string_ci_to_symbol (str)
     Return the symbol whose name is STR.  STR is converted to lowercase before the conversion is done, if Guile is currently reading symbols case-insensitively.

 -- Scheme Procedure: symbol->string s
 -- C Function: scm_symbol_to_string (s)
     Return the name of SYMBOL as a string.  If the symbol was part of an object returned as the value of a literal expression (section see Literal expressions (The Revised^5 Report on Scheme)) or by a call to the 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 string->symbol, the case of characters in the string returned will be the same as the case in the string that was passed to string->symbol.  It is an error to apply mutation procedures like string-set! to strings returned by this procedure.

     The following examples assume that the implementation's standard case is lower case:

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

 -- Scheme Procedure: symbol-hash symbol
 -- C Function: scm_symbol_hash (symbol)
     Return a hash value for SYMBOL.

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

Using Symbols as Discrete Values
--------------------------------

Symbols are especially useful because two symbols which are spelled the same way are equivalent in the sense of 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 (see Association Lists) or hash tables (see Hash Tables), because this usage improves the readability a lot, and does not cause any performance loss.

Function Slots and Property Lists
---------------------------------

 -- Scheme Procedure: symbol-fref symbol
 -- C Function: scm_symbol_fref (symbol)
     Return the contents of SYMBOL's function slot.

 -- Scheme Procedure: symbol-fset! symbol value
 -- C Function: scm_symbol_fset_x (symbol, value)
     Change the binding of SYMBOL's function slot.

 -- Scheme Procedure: symbol-pref symbol
 -- C Function: scm_symbol_pref (symbol)
     Return the property list currently associated with SYMBOL.

 -- Scheme Procedure: symbol-pset! symbol value
 -- C Function: scm_symbol_pset_x (symbol, value)
     Change the binding of SYMBOL's property slot.

Keywords
========

Keywords are self-evaluating objects with a convenient read syntax that makes them easy to type.

Guile's keyword support conforms to R5RS, and adds a (switchable) read syntax extension to permit keywords to begin with : as well as #:.

Why Use Keywords?
-----------------

Keywords are useful in contexts where a program or procedure wants to be able to accept a large number of optional arguments without making its interface unmanageable.

To illustrate this, consider a hypothetical make-window procedure, which creates a new window on the screen for drawing into using some graphical toolkit.  There are many parameters that the caller might like to specify, but which could also be sensibly defaulted, for example:

  * colour depth -- Default: the colour depth for the screen

  * background colour -- Default: white

  * width -- Default: 600

  * height -- Default: 400

If make-window did not use keywords, the caller would have to pass in a value for each possible argument, remembering the correct argument order and using a special value to indicate the default value for that argument:

     (make-window 'default              ;; Colour depth
                  'default              ;; Background colour
                  800                   ;; Width
                  100                   ;; Height
                  ...)                  ;; More make-window arguments

With keywords, on the other hand, defaulted arguments are omitted, and non-default arguments are clearly tagged by the appropriate keyword.  As a result, the invocation becomes much clearer:

     (make-window #:width 800 #:height 100)

On the other hand, for a simpler procedure with few arguments, the use of keywords would be a hindrance rather than a help.  The primitive procedure cons, for example, would not be improved if it had to be invoked as

     (cons #:car x #:cdr y)

So the decision whether to use keywords or not is purely pragmatic: use them if they will clarify the procedure invocation at point of call.

Coding With Keywords
--------------------

If a procedure wants to support keywords, it should take a rest argument and then use whatever means is convenient to extract keywords and their corresponding arguments from the contents of that rest argument.

The following example illustrates the principle: the code for make-window uses a helper procedure called get-keyword-value to extract individual keyword arguments from the rest argument.

     (define (get-keyword-value args keyword default)
       (let ((kv (memq keyword args)))
         (if (and kv (>= (length kv) 2))
             (cadr kv)
             default)))

     (define (make-window . args)
       (let ((depth  (get-keyword-value args #:depth  screen-depth))
             (bg     (get-keyword-value args #:bg     "white"))
             (width  (get-keyword-value args #:width  800))
             (height (get-keyword-value args #:height 100))
             ...)
         ...))

But you don't need to write get-keyword-value.  The (ice-9 optargs) module provides a set of powerful macros that you can use to implement keyword-supporting procedures like this:

     (use-modules (ice-9 optargs))

     (define (make-window . args)
       (let-keywords args #f ((depth  screen-depth)
                              (bg     "white")
                              (width  800)
                              (height 100))
         ...))

Or, even more economically, like this:

     (use-modules (ice-9 optargs))

     (define* (make-window #:key (depth  screen-depth)
                                 (bg     "white")
                                 (width  800)
                                 (height 100))
       ...)

For further details on let-keywords, define* and other facilities provided by the (ice-9 optargs) module, see Optional Arguments.

Keyword Read Syntax
-------------------

Guile, by default, only recognizes the keyword syntax specified by R5RS. A token of the form #:NAME, where NAME has the same syntax as a Scheme symbol (see Symbol Read Syntax), is the external representation of the keyword named NAME.  Keyword objects print using this syntax as well, so values containing keyword objects can be read back into Guile.  When used in an expression, keywords are self-quoting objects.

If the keyword read option is set to 'prefix, Guile also recognizes the alternative read syntax :NAME.  Otherwise, tokens of the form :NAME are read as symbols, as required by R5RS.

To enable and disable the alternative non-R5RS keyword syntax, you use the read-options procedure documented in General option interface and Reader options.

     (read-set! keywords 'prefix)

     #:type
     =>
     #:type

     :type
     =>
     #:type

     (read-set! keywords #f)

     #:type
     =>
     #:type

     :type
     -|
     ERROR: In expression :type:
     ERROR: Unbound variable: :type
     ABORT: (unbound-variable)

Keyword Procedures
------------------

The following procedures can be used for converting symbols to keywords and back.

 -- Scheme Procedure: symbol->keyword sym
     Return a keyword with the same characters as in SYM.

 -- Scheme Procedure: keyword->symbol kw
     Return a symbol with the same characters as in KW.

Keyword Primitives
------------------

Internally, a keyword is implemented as something like a tagged symbol, where the tag identifies the keyword as being self-evaluating, and the symbol, known as the keyword's dash symbol has the same name as the keyword name but prefixed by a single dash.  For example, the keyword #:name has the corresponding dash symbol -name.

Most keyword objects are constructed automatically by the reader when it reads a token beginning with #:.  However, if you need to construct a keyword object programmatically, you can do so by calling make-keyword-from-dash-symbol with the corresponding dash symbol (as the reader does).  The dash symbol for a keyword object can be retrieved using the keyword-dash-symbol procedure.

 -- Scheme Procedure: make-keyword-from-dash-symbol symbol
 -- C Function: scm_make_keyword_from_dash_symbol (symbol)
     Make a keyword object from a SYMBOL that starts with a dash.

 -- Scheme Procedure: keyword? obj
 -- C Function: scm_keyword_p (obj)
     Return #t if the argument OBJ is a keyword, else #f.

 -- Scheme Procedure: keyword-dash-symbol keyword
 -- C Function: scm_keyword_dash_symbol (keyword)
     Return the dash symbol for KEYWORD. This is the inverse of make-keyword-from-dash-symbol.

``Functionality-Centric'' Data Types
====================================

Procedures and macros are documented in their own chapter: see Procedures and Macros.

Variable objects are documented as part of the description of Guile's module system: see Variables.

Asyncs, dynamic roots and fluids are described in the chapter on scheduling: see Scheduling.

Hooks are documented in the chapter on general utility functions: see Hooks.

Ports are described in the chapter on I/O: see Input and Output.