diff options
Diffstat (limited to 'doc/ref/api-data.texi')
-rw-r--r-- | doc/ref/api-data.texi | 80 |
1 files changed, 49 insertions, 31 deletions
diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi index 9bb674a96..ac778b9de 100644 --- a/doc/ref/api-data.texi +++ b/doc/ref/api-data.texi @@ -1686,19 +1686,15 @@ starts from 0 for the least significant bit. @end lisp @end deffn -@deffn {Scheme Procedure} ash n cnt -@deffnx {C Function} scm_ash (n, cnt) -Return @var{n} shifted left by @var{cnt} bits, or shifted right if -@var{cnt} is negative. This is an ``arithmetic'' shift. +@deffn {Scheme Procedure} ash n count +@deffnx {C Function} scm_ash (n, count) +Return @math{floor(n * 2^count)}. +@var{n} and @var{count} must be exact integers. -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.) - -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. +With @var{n} viewed as an infinite-precision twos-complement +integer, @code{ash} means a left shift introducing zero bits +when @var{count} is positive, or a right shift dropping bits +when @var{count} is negative. This is an ``arithmetic'' shift. @lisp (number->string (ash #b1 3) 2) @result{} "1000" @@ -1709,6 +1705,28 @@ dropping bits. @end lisp @end deffn +@deffn {Scheme Procedure} round-ash n count +@deffnx {C Function} scm_round_ash (n, count) +Return @math{round(n * 2^count)}. +@var{n} and @var{count} must be exact integers. + +With @var{n} viewed as an infinite-precision twos-complement +integer, @code{round-ash} means a left shift introducing zero +bits when @var{count} is positive, or a right shift rounding +to the nearest integer (with ties going to the nearest even +integer) when @var{count} is negative. This is a rounded +``arithmetic'' shift. + +@lisp +(number->string (round-ash #b1 3) 2) @result{} \"1000\" +(number->string (round-ash #b1010 -1) 2) @result{} \"101\" +(number->string (round-ash #b1010 -2) 2) @result{} \"10\" +(number->string (round-ash #b1011 -2) 2) @result{} \"11\" +(number->string (round-ash #b1101 -2) 2) @result{} \"11\" +(number->string (round-ash #b1110 -2) 2) @result{} \"100\" +@end lisp +@end deffn + @deffn {Scheme Procedure} logcount n @deffnx {C Function} scm_logcount (n) Return the number of bits in integer @var{n}. If @var{n} is @@ -2049,7 +2067,7 @@ number of one to eight digits. @rnindex char? @deffn {Scheme Procedure} char? x @deffnx {C Function} scm_char_p (x) -Return @code{#t} iff @var{x} is a character, else @code{#f}. +Return @code{#t} if @var{x} is a character, else @code{#f}. @end deffn Fundamentally, the character comparison operations below are @@ -2057,31 +2075,31 @@ numeric comparisons of the character's code points. @rnindex char=? @deffn {Scheme Procedure} char=? x y -Return @code{#t} iff code point of @var{x} is equal to the code point +Return @code{#t} if code point of @var{x} is equal to the code point of @var{y}, else @code{#f}. @end deffn @rnindex char<? @deffn {Scheme Procedure} char<? x y -Return @code{#t} iff the code point of @var{x} is less than the code +Return @code{#t} if the code point of @var{x} is less than the code point of @var{y}, else @code{#f}. @end deffn @rnindex char<=? @deffn {Scheme Procedure} char<=? x y -Return @code{#t} iff the code point of @var{x} is less than or equal +Return @code{#t} if the code point of @var{x} is less than or equal to the code point of @var{y}, else @code{#f}. @end deffn @rnindex char>? @deffn {Scheme Procedure} char>? x y -Return @code{#t} iff the code point of @var{x} is greater than the +Return @code{#t} if the code point of @var{x} is greater than the code point of @var{y}, else @code{#f}. @end deffn @rnindex char>=? @deffn {Scheme Procedure} char>=? x y -Return @code{#t} iff the code point of @var{x} is greater than or +Return @code{#t} if the code point of @var{x} is greater than or equal to the code point of @var{y}, else @code{#f}. @end deffn @@ -2099,32 +2117,32 @@ it cannot cover all cases for all languages. @rnindex char-ci=? @deffn {Scheme Procedure} char-ci=? x y -Return @code{#t} iff the case-folded code point of @var{x} is the same +Return @code{#t} if the case-folded code point of @var{x} is the same as the case-folded code point of @var{y}, else @code{#f}. @end deffn @rnindex char-ci<? @deffn {Scheme Procedure} char-ci<? x y -Return @code{#t} iff the case-folded code point of @var{x} is less +Return @code{#t} if the case-folded code point of @var{x} is less than the case-folded code point of @var{y}, else @code{#f}. @end deffn @rnindex char-ci<=? @deffn {Scheme Procedure} char-ci<=? x y -Return @code{#t} iff the case-folded code point of @var{x} is less +Return @code{#t} if the case-folded code point of @var{x} is less than or equal to the case-folded code point of @var{y}, else @code{#f}. @end deffn @rnindex char-ci>? @deffn {Scheme Procedure} char-ci>? x y -Return @code{#t} iff the case-folded code point of @var{x} is greater +Return @code{#t} if the case-folded code point of @var{x} is greater than the case-folded code point of @var{y}, else @code{#f}. @end deffn @rnindex char-ci>=? @deffn {Scheme Procedure} char-ci>=? x y -Return @code{#t} iff the case-folded code point of @var{x} is greater +Return @code{#t} if the case-folded code point of @var{x} is greater than or equal to the case-folded code point of @var{y}, else @code{#f}. @end deffn @@ -2132,36 +2150,36 @@ than or equal to the case-folded code point of @var{y}, else @rnindex char-alphabetic? @deffn {Scheme Procedure} char-alphabetic? chr @deffnx {C Function} scm_char_alphabetic_p (chr) -Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}. +Return @code{#t} if @var{chr} is alphabetic, else @code{#f}. @end deffn @rnindex char-numeric? @deffn {Scheme Procedure} char-numeric? chr @deffnx {C Function} scm_char_numeric_p (chr) -Return @code{#t} iff @var{chr} is numeric, else @code{#f}. +Return @code{#t} if @var{chr} is numeric, else @code{#f}. @end deffn @rnindex char-whitespace? @deffn {Scheme Procedure} char-whitespace? chr @deffnx {C Function} scm_char_whitespace_p (chr) -Return @code{#t} iff @var{chr} is whitespace, else @code{#f}. +Return @code{#t} if @var{chr} is whitespace, else @code{#f}. @end deffn @rnindex char-upper-case? @deffn {Scheme Procedure} char-upper-case? chr @deffnx {C Function} scm_char_upper_case_p (chr) -Return @code{#t} iff @var{chr} is uppercase, else @code{#f}. +Return @code{#t} if @var{chr} is uppercase, else @code{#f}. @end deffn @rnindex char-lower-case? @deffn {Scheme Procedure} char-lower-case? chr @deffnx {C Function} scm_char_lower_case_p (chr) -Return @code{#t} iff @var{chr} is lowercase, else @code{#f}. +Return @code{#t} if @var{chr} is lowercase, else @code{#f}. @end deffn @deffn {Scheme Procedure} char-is-both? chr @deffnx {C Function} scm_char_is_both_p (chr) -Return @code{#t} iff @var{chr} is either uppercase or lowercase, else +Return @code{#t} if @var{chr} is either uppercase or lowercase, else @code{#f}. @end deffn @@ -2583,8 +2601,8 @@ string is not defined. @deffn {Scheme Procedure} char-set-contains? cs ch @deffnx {C Function} scm_char_set_contains_p (cs, ch) -Return @code{#t} iff the character @var{ch} is contained in the -character set @var{cs}. +Return @code{#t} if the character @var{ch} is contained in the +character set @var{cs}, or @code{#f} otherwise. @end deffn @deffn {Scheme Procedure} char-set-every pred cs |