arithmetic, the @samp{+inf.0}, @samp{-inf.0}, and @samp{+nan.0} values
are implemented using the corresponding @acronym{IEEE} 754 values.
They behave in arithmetic operations like @acronym{IEEE} 754 describes
-it, i.e., @code{(= +nan.0 +nan.0) @result{#f}}.
+it, i.e., @code{(= +nan.0 +nan.0)} @result{} @code{#f}.
The infinities are inexact integers and are considered to be both even
and odd. While @samp{+nan.0} is not @code{=} to itself, it is
@end deffn
@c begin (texi-doc-string "guile" "quotient")
-@deffn {Scheme Procedure} quotient
-Return the quotient of the numbers @var{x} and @var{y}.
-@end deffn
-
@c begin (texi-doc-string "guile" "remainder")
-@deffn {Scheme Procedure} remainder
-Return the remainder of the numbers @var{x} and @var{y}.
+@deffn {Scheme Procedure} quotient n d
+@deffnx {Scheme Procedure} remainder n d
+Return the quotient or remainder from @var{n} divided by @var{d}. The
+quotient is rounded towards zero, and the remainder will have the same
+sign as @var{n}. In all cases quotient and remainder satisfy
+@math{@var{n} = @var{q}*@var{d} + @var{r}}.
+
@lisp
(remainder 13 4) @result{} 1
(remainder -13 4) @result{} -1
@end deffn
@c begin (texi-doc-string "guile" "modulo")
-@deffn {Scheme Procedure} modulo
-Return the modulo of the numbers @var{x} and @var{y}.
+@deffn {Scheme Procedure} modulo n d
+Return the remainder from @var{n} divided by @var{d}, with the same
+sign as @var{d}.
+
@lisp
(modulo 13 4) @result{} 1
(modulo -13 4) @result{} 3
+(modulo 13 -4) @result{} -3
+(modulo -13 -4) @result{} -1
@end lisp
@end deffn
@end deffn
@c begin (texi-doc-string "guile" "real-part")
-@deffn {Scheme Procedure} real-part
+@deffn {Scheme Procedure} real-part z
Return the real part of the number @var{z}.
@end deffn
@c begin (texi-doc-string "guile" "imag-part")
-@deffn {Scheme Procedure} imag-part
+@deffn {Scheme Procedure} imag-part z
Return the imaginary part of the number @var{z}.
@end deffn
@c begin (texi-doc-string "guile" "magnitude")
-@deffn {Scheme Procedure} magnitude
+@deffn {Scheme Procedure} magnitude z
Return the magnitude of the number @var{z}. This is the same as
@code{abs} for real arguments, but also allows complex numbers.
@end deffn
@c begin (texi-doc-string "guile" "angle")
-@deffn {Scheme Procedure} angle
+@deffn {Scheme Procedure} angle z
Return the angle of the complex number @var{z}.
@end deffn
@c begin (texi-doc-string "guile" "round")
@deffn {Scheme Procedure} round x
-Round the inexact number @var{x} towards zero.
+Round the inexact number @var{x} to the nearest integer. When exactly
+halfway between two integers, round to the even one.
@end deffn
@c begin (texi-doc-string "guile" "floor")
Round the number @var{x} towards infinity.
@end deffn
-For the @code{truncate} and @code{round} procedures, the Guile library
-exports equivalent C functions, but taking and returning arguments of
-type @code{double} rather than the usual @code{SCM}.
+C functions for some of the above rounding functions are provided by
+the standard C mathematics library. Naturally these expect and return
+@code{double} arguments (@pxref{Rounding Functions,,, libc, GNU C
+Library Reference Manual}).
+
+@multitable {xx} {Scheme Procedure} {C Function}
+@item @tab Scheme Procedure @tab C Function
+@item @tab @code{floor} @tab @code{floor}
+@item @tab @code{ceiling} @tab @code{ceil}
+@item @tab @code{truncate} @tab @code{trunc}
+@end multitable
+
+@code{trunc} is C99 standard and might not be available on older
+systems. Guile provides an @code{scm_truncate} equivalent (on all
+systems), plus a C level version of the Scheme @code{round} procedure.
@deftypefn {C Function} double scm_truncate (double x)
@deftypefnx {C Function} double scm_round (double x)
@end deftypefn
-For @code{floor} and @code{ceiling}, the equivalent C functions are
-@code{floor} and @code{ceil} from the standard mathematics library
-(which also take and return @code{double} arguments).
-
@node Scientific
@subsection Scientific Functions
@rnindex atan
@c begin (texi-doc-string "guile" "atan")
@deffn {Scheme Procedure} atan z
-Return the arctangent of @var{z}.
+@deffnx {Scheme Procedure} atan y x
+Return the arctangent of @var{z}, or of @math{@var{y}/@var{x}}.
@end deffn
@rnindex exp
Return the hyperbolic arctangent of @var{x}.
@end deffn
-For the hyperbolic arc-functions, the Guile library exports C functions
-corresponding to these Scheme procedures, but taking and returning
-arguments of type @code{double} rather than the usual @code{SCM}.
-
-@deftypefn {C Function} double scm_asinh (double x)
-@deftypefnx {C Function} double scm_acosh (double x)
-@deftypefnx {C Function} double scm_atanh (double x)
-Return the hyperbolic arcsine, arccosine or arctangent of @var{x}
-respectively.
-@end deftypefn
-
-For all the other Scheme procedures above, except @code{expt} and
-@code{atan2} (whose entries specifically mention an equivalent C
-function), the equivalent C functions are those provided by the standard
-mathematics library. The mapping is as follows.
+C functions for the above are provided by the standard mathematics
+library. Naturally these expect and return @code{double} arguments
+(@pxref{Mathematics,,, libc, GNU C Library Reference Manual}).
@multitable {xx} {Scheme Procedure} {C Function}
@item @tab Scheme Procedure @tab C Function
@item @tab @code{$asin} @tab @code{asin}
@item @tab @code{$acos} @tab @code{acos}
@item @tab @code{$atan} @tab @code{atan}
+@item @tab @code{$atan2} @tab @code{atan2}
@item @tab @code{$exp} @tab @code{exp}
+@item @tab @code{$expt} @tab @code{pow}
@item @tab @code{$log} @tab @code{log}
@item @tab @code{$sinh} @tab @code{sinh}
@item @tab @code{$cosh} @tab @code{cosh}
@item @tab @code{$tanh} @tab @code{tanh}
+@item @tab @code{$asinh} @tab @code{asinh}
+@item @tab @code{$acosh} @tab @code{acosh}
+@item @tab @code{$atanh} @tab @code{atanh}
@end multitable
-@noindent
-Naturally, these C functions expect and return @code{double} arguments.
+@code{asinh}, @code{acosh} and @code{atanh} are C99 standard but might
+not be available on older systems. Guile provides the following
+equivalents (on all systems).
+
+@deftypefn {C Function} double scm_asinh (double x)
+@deftypefnx {C Function} double scm_acosh (double x)
+@deftypefnx {C Function} double scm_atanh (double x)
+Return the hyperbolic arcsine, arccosine or arctangent of @var{x}
+respectively.
+@end deftypefn
@node Bitwise Operations
@subsection Bitwise Operations
-@deffn {Scheme Procedure} logand n1 n2
+For the following bitwise functions, negative numbers are treated as
+infinite precision twos-complements. For instance @math{-6} is bits
+@math{@dots{}111010}, with infinitely many ones on the left. It can
+be seen that adding 6 (binary 110) to such a bit pattern gives all
+zeros.
+
+@deffn {Scheme Procedure} logand n1 n2 @dots{}
Return the bitwise @sc{and} of the integer arguments.
@lisp
@end lisp
@end deffn
-@deffn {Scheme Procedure} logior n1 n2
+@deffn {Scheme Procedure} logior n1 n2 @dots{}
Return the bitwise @sc{or} of the integer arguments.
@lisp
@end lisp
@end deffn
-@deffn {Scheme Procedure} logxor n1 n2
+@deffn {Scheme Procedure} logxor n1 n2 @dots{}
Return the bitwise @sc{xor} of the integer arguments. A bit is
set in the result if it is set in an odd number of arguments.
+
@lisp
(logxor) @result{} 0
(logxor 7) @result{} 7
@deffn {Scheme Procedure} lognot n
@deffnx {C Function} scm_lognot (n)
-Return the integer which is the 2s-complement of the integer
-argument.
+Return the integer which is the ones-complement of the integer
+argument, ie.@: each 0 bit is changed to 1 and each 1 bit to 0.
@lisp
(number->string (lognot #b10000000) 2)
@deffn {Scheme Procedure} ash n cnt
@deffnx {C Function} scm_ash (n, cnt)
-The function @code{ash} performs an arithmetic shift left by @var{cnt}
-bits (or shift right, if @var{cnt} is negative). `Arithmetic'
-means that the function does not guarantee to keep the bit
-structure of @var{n}, but rather guarantees that the result
-will always be rounded towards minus infinity. Therefore, the
-results of @code{ash} and a corresponding bitwise shift will differ if
-@var{n} is negative.
+Return @var{n} shifted left by @var{cnt} bits, or shifted right if
+@var{cnt} is negative. This is an ``arithmetic'' shift.
+
+This is effectively a multiplication by @m{2^{cnt}, 2^@var{cnt}}, and
+when @var{cnt} is negative it's a division, rounded towards negative
+infinity. (Note that this is not the same rounding as @code{quotient}
+does.)
-Formally, the function returns an integer equivalent to
-@code{(inexact->exact (floor (* @var{n} (expt 2 @var{cnt}))))}.
+With @var{n} viewed as an infinite precision twos complement,
+@code{ash} means a left shift introducing zero bits, or a right shift
+dropping bits.
@lisp
(number->string (ash #b1 3) 2) @result{} "1000"
(number->string (ash #b1010 -1) 2) @result{} "101"
+
+;; -23 is bits ...11101001, -6 is bits ...111010
+(ash -23 -2) @result{} -6
@end lisp
@end deffn
@deffnx {C Function} scm_integer_length (n)
Return the number of bits necessary to represent @var{n}.
+For positive @var{n} this is how many bits to the most significant one
+bit. For negative @var{n} it's how many bits to the most significant
+zero bit in twos complement form.
+
@lisp
-(integer-length #b10101010)
- @result{} 8
-(integer-length 0)
- @result{} 0
-(integer-length #b1111)
- @result{} 4
+(integer-length #b10101010) @result{} 8
+(integer-length #b1111) @result{} 4
+(integer-length 0) @result{} 0
+(integer-length -1) @result{} 0
+(integer-length -256) @result{} 8
+(integer-length -257) @result{} 9
@end lisp
@end deffn
(string->symbol "K. Harper, M.D."))) @result{} #t
@end lisp
+From C, there are lower level functions that construct a Scheme symbol
+from a null terminated C string or from a sequence of bytes whose length
+is specified explicitly.
+
+@deffn {C Function} scm_str2symbol (const char * name)
+@deffnx {C Function} scm_mem2symbol (const char * name, size_t len)
+Construct and return a Scheme symbol whose name is specified by
+@var{name}. For @code{scm_str2symbol} @var{name} must be null
+terminated; For @code{scm_mem2symbol} the length of @var{name} is
+specified explicitly by @var{len}.
+@end deffn
+
Finally, some applications, especially those that generate new Scheme
code dynamically, need to generate symbols for use in the generated
code. The @code{gensym} primitive meets this need:
@deffnx {C Function} scm_gensym (prefix)
Create a new symbol with a name constructed from a prefix and a counter
value. The string @var{prefix} can be specified as an optional
-argument. Default prefix is @samp{ g}. The counter is increased by 1
+argument. Default prefix is @samp{@w{ g}}. The counter is increased by 1
at each call. There is no provision for resetting the counter.
@end deffn
The symbols generated by @code{gensym} are @emph{likely} to be unique,
since their names begin with a space and it is only otherwise possible
to generate such symbols if a programmer goes out of their way to do
-so. The 1.8 release of Guile will include a way of creating
-symbols that are @emph{guaranteed} to be unique.
+so. Uniqueness can be guaranteed by instead using uninterned symbols
+(@pxref{Symbol Uninterned}), though they can't be usefully written out
+and read back in.
@node Symbol Props
@deffn {Scheme Procedure} make-keyword-from-dash-symbol symbol
@deffnx {C Function} scm_make_keyword_from_dash_symbol (symbol)
Make a keyword object from a @var{symbol} that starts with a dash.
+For example,
+
+@example
+(make-keyword-from-dash-symbol '-foo)
+@result{} #:foo
+@end example
@end deffn
@deffn {Scheme Procedure} keyword? obj
@deffnx {C Function} scm_keyword_dash_symbol (keyword)
Return the dash symbol for @var{keyword}.
This is the inverse of @code{make-keyword-from-dash-symbol}.
+For example,
+
+@example
+(keyword-dash-symbol #:foo)
+@result{} -foo
+@end example
@end deffn
+@deftypefn {C Function} SCM scm_c_make_keyword (char *@var{str})
+Make a keyword object from a string. For example,
+
+@example
+scm_c_make_keyword ("foo")
+@result{} #:foo
+@end example
+@c
+@c FIXME: What can be said about the string argument? Currently it's
+@c not used after creation, but should that be documented?
+@end deftypefn
+
@node Other Types
@section ``Functionality-Centric'' Data Types
HCoop / bpt / guile.git / blobdiff