diff --git a/collects/scribble/latex-render.ss b/collects/scribble/latex-render.ss index 129f1acd41..161a319d85 100644 --- a/collects/scribble/latex-render.ss +++ b/collects/scribble/latex-render.ss @@ -321,6 +321,7 @@ [(#\u03B1) (display "$\\alpha$")] [(#\u03BF) (display "o")] ; omicron [(#\u03C3) (display "$\\sigma$")] + [(#\u03C2) (display "$\\varsigma$")] [(#\u03BB) (display "$\\lambda$")] [(#\u03BC) (display "$\\mu$")] [else (display c)])) diff --git a/collects/scribblings/reference/bytes.scrbl b/collects/scribblings/reference/bytes.scrbl index 42fdd52a5a..963521e951 100644 --- a/collects/scribblings/reference/bytes.scrbl +++ b/collects/scribblings/reference/bytes.scrbl @@ -15,9 +15,8 @@ string is provided to a procedure like @scheme[bytes-set!], the @exnraise[exn:fail:contract]. Byte-string constants generated by the default reader (see @secref["mz:parse-string"]) are immutable. -Two byte strings are @scheme[eq?] when mutating one would mutate the -other. Two byte strings are @scheme[eqv?] and @scheme[equal?] when -they have the same length and contain the same sequence of bytes. +Two byte strings are @scheme[equal?] when they have the same length +and contain the same sequence of bytes. A byte string can be used as a single-valued sequence (see @secref["mz:sequences"]). The bytes of the string serve as elements @@ -333,3 +332,214 @@ positions are initialized with the given @scheme[b]s. @; ---------------------------------------- @section{Bytes to Bytes Encoding Conversion} +@defproc[(bytes-open-converter [from-name string?][to-name string?]) + bytes-converter?]{ + +Produces a string converter to go from the encoding named by +@scheme[from-name] to the encoding named by @scheme[to-name]. If the +requested conversion pair is not available, @scheme[#f] is returned +instead of a converter. + +Certain encoding combinations are always available: + + @itemize{ + + @item{@scheme[(bytes-open-converter "UTF-8" "UTF-8")] --- the + identity conversion, except that encoding errors in the input lead + to a decoding failure.} + + @item{@scheme[(bytes-open-converter "UTF-8-permissive" "UTF-8")] --- + the identity conversion, except that any input byte that is not + part of a valid encoding sequence is effectively replaced by + @scheme[(char->integer #\?)]. (This handling of invalid sequences + is consistent with the interpretation of port bytes streams into + characters; see @secref["mz:ports"].)} + + @item{@scheme[(bytes-open-converter "" "UTF-8")] --- converts from + the current locale's default encoding (see @secref["mz:locales"]) + to UTF-8.} + + @item{@scheme[(bytes-open-converter "UTF-8" "")] --- converts from + UTF-8 to the current locale's default encoding (see + @secref["mz:locales"]).} + + @item{@scheme[(bytes-open-converter "platform-UTF-8" "platform-UTF-16")] + --- converts UTF-8 to UTF-16 under @|AllUnix|, where each UTF-16 + code unit is a sequence of two bytes ordered by the current + platform's endianess. Under Windows, the input can include + encodings that are not valid UTF-8, but which naturally extend the + UTF-8 encoding to support unpaired surrogate code units, and the + output is a sequence of UTF-16 code units (as little-endian byte + pairs), potentially including unpaired surrogates.} + + @item{@scheme[(bytes-open-converter "platform-UTF-8-permissive" "platform-UTF-16")] + --- like @scheme[(bytes-open-converter "platform-UTF-8" "platform-UTF-16")], + but an input byte that is not part of a valid UTF-8 encoding + sequence (or valid for the unpaired-surrogate extension under + Windows) is effectively replaced with @scheme[(char->integer #\?)].} + + @item{@scheme[(bytes-open-converter "platform-UTF-16" "platform-UTF-8")] + --- converts UTF-16 (bytes orderd by the current platform's + endianness) to UTF-8 under @|AllUnix|. Under Windows, the input can + include UTF-16 code units that are unpaired surrogates, and the + corresponding output includes an encoding of each surrogate in a + natural extension of UTF-8. Under @|AllUnix|, surrogates are + assumed to be paired: a pair of bytes with the bits @scheme[#xD800] + starts a surrogate pair, and the @scheme[#x03FF] bits are used from + the pair and following pair (independent of the value of the + @scheme[#xDC00] bits). On all platforms, performance may be poor + when decoding from an odd offset within an input byte string.} + + } + +A newly opened byte converter is registered with the current custodian +(see @secref["mz:custodians"]), so that the converter is closed when +the custodian is shut down. A converter is not registered with a +custodian (and does not need to be closed) if it is one of the +guaranteed combinations not involving @scheme[""] under Unix, or if it +is any of the guaranteed combinations (including @scheme[""]) under +Windows and Mac OS X. + +@margin-note{In PLT's software distributions for Windows, a suitable +@file{iconv.dll} is included with @file{libmzsch@italic{VERS}.dll}.} + +The set of available encodings and combinations varies by platform, +depending on the @exec{iconv} library that is installed. Under +Windows, @file{iconv.dll} or @file{libiconv.dll} must be in the same +directory as @file{libmzsch@italic{VERS}.dll} (where @italic{VERS} is +a version number), in the user's path, in the system directory, or in +the current executable's directory at run time, and the DLL must +either supply @tt{_errno} or link to @file{msvcrt.dll} for +@tt{_errno}; otherwise, only the guaranteed combinations are +available.} + + +@defproc[(bytes-close-converter [converter bytes-converter?]) void]{ + +Closes the given converter, so that it can no longer be used with +@scheme[bytes-convert] or @scheme[bytes-convert-end].} + + +@defproc[(bytes-convert [converter bytes-converter?] + [src-bstr bytes?] + [src-start-pos nonnegative-exact-integer? 0] + [src-end-pos nonnegative-exact-integer? (bytes-length src-bstr)] + [dest-bstr (or/c bytes? false/c) #f] + [dest-start-pos nonnegative-exact-integer? 0] + [dest-end-pos (or/c nonnegative-exact-integer? false/c) + (and dest-bstr + (bytes-length dest-bstr))]) + (values (or/c bytes? nonnegative-exact-integer?) + nonnegative-exact-integer? + (one-of 'complete 'continues 'aborts 'error))]{ + +Converts the bytes from @scheme[src-start-pos] to @scheme[src-end-pos] +in @scheme[src-bstr]. + +If @scheme[dest-bstr] is not @scheme[#f], the converted byte are +written into @scheme[dest-bstr] from @scheme[dest-start-pos] to +@scheme[dest-end-pos]. If @scheme[dest-bstr] is @scheme[#f], then a +newly allocated byte string holds the conversion results, and if +@scheme[dest-end-pos] is not @scheme[#f], the size of the result byte +string is no more than @scheme[(- dest-end-pos dest-start-pos)]. + +The result of @scheme[bytes-convert] is three values: + + @itemize{ + + @item{@scheme[_result-bstr] or @scheme[_dest-wrote-amt] --- a byte + string if @scheme[dest-bstr] is @scheme[#f] or not provided, or the + number of bytes written into @scheme[dest-bstr] otherwise.} + + @item{@scheme[_src-read-amt] --- the number of bytes successfully converted + from @scheme[src-bstr].} + + @item{@scheme['complete], @scheme['continues], + @scheme['aborts], or @scheme['error] --- indicates how + conversion terminated: + + @itemize{ + + @item{@scheme['complete]: The entire input was processed, and + @scheme[_src-read-amt] will be equal to @scheme[(- src-end-pos + src-start-pos)].} + + @item{@scheme['continues]: Conversion stopped due to the limit on + the result size or the space in @scheme[dest-bstr]; in this case, + fewer than @scheme[(- dest-end-pos dest-start-pos)] bytes may be + returned if more space is needed to process the next complete + encoding sequence in @scheme[src-bstr].} + + @item{@scheme['aborts]: The input stopped part-way through an + encoding sequence, and more input bytes are necessary to continue. + For example, if the last byte of input is @scheme[#o303] for a + @scheme["UTF-8-permissive"] decoding, the result is + @scheme['aborts], because another byte is needed to determine how to + use the @scheme[#o303] byte.} + + @item{@scheme['error]: The bytes starting at @scheme[(+ + src-start-pos _src-read-amt)] bytes in @scheme[src-bstr] do not form + a legal encoding sequence. This result is never produced for some + encodings, where all byte sequences are valid encodings. For + example, since @scheme["UTF-8-permissive"] handles an invalid UTF-8 + sequence by dropping characters or generating ``?,'' every byte + sequence is effectively valid.} + + }} + } + +Applying a converter accumulates state in the converter (even when the +third result of @scheme[bytes-convert] is @scheme['complete]). This +state can affect both further processing of input and further +generation of output, but only for conversions that involve ``shift +sequences'' to change modes within a stream. To terminate an input +sequence and reset the converter, use @scheme[bytes-convert-end].} + + +@defproc[(bytes-convert-end [converter bytes-converter?] + [dest-bstr (or/c bytes? false/c) #f] + [dest-start-pos nonnegative-exact-integer? 0] + [dest-end-pos (or/c nonnegative-exact-integer? false/c) + (and dest-bstr + (bytes-length dest-bstr))]) + (values (or/c bytes? nonnegative-exact-integer?) + (one-of 'complete 'continues))]{ + +Like @scheme[bytes-convert], but instead of converting bytes, this +procedure generates an ending sequence for the conversion (sometimes +called a ``shift sequence''), if any. Few encodings use shift +sequences, so this function will succeed with no output for most +encodings. In any case, successful output of a (possibly empty) shift +sequence resets the converter to its initial state. + +The result of @scheme[bytes-convert-end] is two values: + + @itemize{ + + @item{@scheme[_result-bstr] or @scheme[_dest-wrote-amt] --- a byte string if + @scheme[dest-bstr] is @scheme[#f] or not provided, or the number of + bytes written into @scheme[dest-bstr] otherwise.} + + @item{@scheme['complete] or @scheme['continues] --- + indicates whether conversion completed. If @scheme['complete], then + an entire ending sequence was produced. If @scheme['continues], then + the conversion could not complete due to the limit on the result + size or the space in @scheme[dest-bstr], and the first result is + either an empty byte string or @scheme[0].} + + } +} + + +@defproc[(bytes-converter? [v any/c]) boolean?]{ + +Returns @scheme[#t] if @scheme[v] is a byte converter produced by +@scheme[bytes-open-converter], @scheme[#f] otherwise.} + + +@defproc[(locale-string-encoding) any]{ + +Returns a string for the current locale's encoding (i.e., the encoding +normally identified by @scheme[""]). See also +@scheme[system-language+country].} + diff --git a/collects/scribblings/reference/chars.scrbl b/collects/scribblings/reference/chars.scrbl index cc9e86a18c..5d3f6279be 100644 --- a/collects/scribblings/reference/chars.scrbl +++ b/collects/scribblings/reference/chars.scrbl @@ -1,20 +1,284 @@ #reader(lib "docreader.ss" "scribble") @require["mz.ss"] +@define[(UCat x) x] + @title[#:tag "mz:characters"]{Characters} @guideintro["guide:characters"]{characters} -A @pidefterm{character} corresponds to a Unicode scalar value (i.e., a -Unicode code point that is not a surrogate). +MzScheme characters range over Unicode scalar values, which includes +characters whose values range from @scheme[#x0] to @scheme[#x10FFFF], +but not including @scheme[#xD800] to @scheme[#xDFFF]. + +Two characters are @scheme[eqv?] if they correspond to the same scalar +value. For each scalar value less than 256, character values that are +@scheme[eqv?] are also @scheme[eq?]. + +@; ---------------------------------------- +@section{Characters and Scalar Values} + +@defproc[(char? [v any/c]) boolean?]{ + +Return @scheme[#t] if @scheme[v] is a character, @scheme[#f] +otherwise.} + + +@defproc[(char->integer [char char?]) exact-integer?]{ + +Returns a character's code-point number. + +@examples[(char->integer #\A)]} + + +@defproc[(integer->char [k (and/c exact-integer? + (or/c (integer-in 0 #xD7FF) + (integer-in #xE000 #x10FFFF)))]) + char?]{ + +Return the character whose code-point number is @scheme[k]. For +@scheme[k] less than @scheme[256], the result is the same object for +the same @scheme[k]. + +@examples[(integer->char 65)]} + + +@defproc[(char-utf-8-length [char char?]) (integer-in 1 6)]{ + +Produces the same result as @scheme[(bytes-length (string->bytes/utf-8 +(string char)))].} + + +@; ---------------------------------------- +@section{Character Comparisons} + +@defproc[(char=? [char1 char?] [char2 char?] ...+) boolean?]{ + +Returns @scheme[#t] if all of the arguments are @scheme[eqv?]. + +@examples[(char=? #\a #\a) + (char=? #\a #\A #\a)]} + +@define[(char-sort direction folded?) + (if folded? + @elem{Like @scheme[char-ci? [char1 char?] [char2 char?] ...+) boolean?]{ + @char-sort["decreasing" #f] + +@examples[(char>? #\A #\a) + (char>? #\a #\A) + (char>? #\c #\b #\a)]} + +@defproc[(char>=? [char1 char?] [char2 char?] ...+) boolean?]{ + @char-sort["nonincreasing" #f] + +@examples[(char>=? #\A #\a) + (char>=? #\a #\A) + (char>=? #\c #\b #\b)]} + + +@defproc[(char-ci=? [char1 char?] [char2 char?] ...+) boolean?]{ + Returns @scheme[#t] if all of the arguments are @scheme[eqv?] after + locale-insensitive case-folding via @scheme[char-foldcase]. + +@examples[(char-ci=? #\A #\a) + (char-ci=? #\a #\a #\a)]} + +@defproc[(char-ci? [char1 char?] [char2 char?] ...+) boolean?]{ + @char-sort["decreasing" #t] + +@examples[(char-ci>? #\A #\a) + (char-ci>? #\b #\A) + (char-ci>? #\c #\b #\a)]} + +@defproc[(char-ci>=? [char1 char?] [char2 char?] ...+) boolean?]{ + @char-sort["nonincreasing" #t] + +@examples[(char-ci>=? #\A #\a) + (char-ci>=? #\a #\A) + (char-ci>=? #\c #\b #\b)]} @; ---------------------------------------- @section{Classifications} -@defproc[(char-alphabetic? [char character?]) boolean?]{ -Returns @scheme[#t] if @scheme[char] is alphabetic... -} +@defproc[(char-alphabetic? [char char?]) boolean?]{ -@defproc[(char-whitespace? [char character?]) boolean?]{ -Returns @scheme[#t] if @scheme[char] is whitespace... -} \ No newline at end of file +Returns @scheme[#t] if @scheme[char]'s Unicode general category is +@UCat{Lu}, @UCat{Ll}, @UCat{Lt}, @UCat{Lm}, or @UCat{Lo}, @scheme[#f] +otherwise.} + +@defproc[(char-lower-case? [char char?]) boolean?]{ + +Returns @scheme[#t] if @scheme[char] has the Unicode ``Lowercase'' +property.} + + +@defproc[(char-upper-case? [char char?]) boolean?]{ + +Returns @scheme[#t] if @scheme[char] has the Unicode ``Uppercase'' +property.} + +@defproc[(char-title-case? [char char?]) boolean?]{ + +Returns @scheme[#t] if @scheme[char]'s Unicode general category is +@UCat{Lt}, @scheme[#f] otherwise.} + +@defproc[(char-numeric? [char char?]) boolean?]{ + +Returns @scheme[#t] if @scheme[char]'s Unicode general category is +@UCat{Nd}, @scheme[#f] otherwise.} + +@defproc[(char-symbolic? [char char?]) boolean?]{ + +Returns @scheme[#t] if @scheme[char]'s Unicode general category is +@UCat{Sm}, @UCat{Sc}, @UCat{Sk}, or @UCat{So}, @scheme[#f] otherwise.} + +@defproc[(char-punctuation? [char char?]) boolean?]{ + +Returns @scheme[#t] if @scheme[char]'s Unicode general category is +@UCat{Pc}, @UCat{Pd}, @UCat{Ps}, @UCat{Pe}, @UCat{Pi}, @UCat{Pf}, or +@UCat{Po}, @scheme[#f] otherwise.} + +@defproc[(char-graphic? [char char?]) boolean?]{ + +Returns @scheme[#t] if @scheme[char]'s Unicode general category is +@UCat{Mn}, @UCat{Mc}, @UCat{Me}, or if one of the following produces +@scheme[#t] when applied to @scheme[char]: @scheme[char-alphabetic?], +@scheme[char-numeric?], @scheme[char-symbolic?], or +@scheme[char-punctuation?].} + +@defproc[(char-whitespace? [char char?]) boolean?]{ + +Returns @scheme[#t] if @scheme[char]'s Unicode general category is +@UCat{Zs}, @UCat{Zl}, or @UCat{Zp}, or if @scheme[char] is one of the +following: @scheme[#\tab], @scheme[#\newline], @scheme[#\vtab], +@scheme[#\page], @scheme[#\return], or @scheme[#\u0085].} + +@defproc[(char-blank? [char char?]) boolean?]{ + +Returns @scheme[#t] if @scheme[char]'s Unicode general category is +@UCat{Zs} or if @scheme[char] is @scheme[#\tab]. (These correspond to +horizontal whitespace.)} + +@defproc[(char-iso-control? [char char?]) boolean?]{ + +Return @scheme[#t] if @scheme[char] is between @scheme[#\u0000] and +@scheme[#\u001F] inclusive or @scheme[#\u007F] and @scheme[#\u009F] +inclusive.} + +@defproc[(char-general-category [char char?]) boolean?]{ + +Returns a symbol representing the character's Unicode general +category, which is @scheme['lu], @scheme['ll], @scheme['lt], +@scheme['lm], @scheme['lo], @scheme['mn], @scheme['mc], @scheme['me], +@scheme['nd], @scheme['nl], @scheme['no], @scheme['ps], @scheme['pe], +@scheme['pi], @scheme['pf], @scheme['pd], @scheme['pc], @scheme['po], +@scheme['sc], @scheme['sm], @scheme['sk], @scheme['so], @scheme['zs], +@scheme['zp], @scheme['zl], @scheme['cc], @scheme['cf], @scheme['cs], +@scheme['co], or @scheme['cn].} + +@defproc[(make-known-char-range-list) + (listof (list/c nonnegative-integer? + nonnegative-integer? + boolean?))]{ + +Produces a list of three-element lists, where each three-element list +represents a set of consecutive code points for which the Unicode +standard specifies character properties. Each three-element list +contains two integers and a boolean; the first integer is a starting +code-point value (inclusive), the second integer is an ending +code-point value (inclusive), and the boolean is @scheme[#t] when all +characters in the code-point range have identical results for all of +the character predicates above. The three-element lists are ordered in +the overall result list such that later lists represent larger +code-point values, and all three-element lists are separated from +every other by at least one code-point value that is not specified by +Unicode.} + + +@; ---------------------------------------- +@section{Character Conversions} + +@defproc[(char-upcase [char char?]) char?]{ + +Produces a character consistent with the 1-to-1 code point mapping +defined by Unicode. If @scheme[char] has no upcase mapping, +@scheme[char-upcase] produces @scheme[char]. + +@margin-note{String procedures, such as @scheme[string-upcase], handle +the case where Unicode defines a locale-independent mapping from the +code point to a code-point sequence (in addition to the 1-1 mapping on +scalar values).} + +@examples[ +(char-upcase #\a) +(char-upcase #\u03BB) +(char-upcase #\space) +]} + + +@defproc[(char-downcase [char char?]) char?]{ + +Like @scheme[char-upcase], but for the Unicode downcase mapping. + +@examples[ +(char-downcase #\A) +(char-downcase #\u039B) +(char-downcase #\space) +]} + +@defproc[(char-titlecase [char char?]) char?]{ + +Like @scheme[char-upcase], but for the Unicode titlecase mapping. + +@examples[ +(char-upcase #\a) +(char-upcase #\u03BB) +(char-upcase #\space) +]} + +@defproc[(char-foldcase [char char?]) char?]{ + +Like @scheme[char-upcase], but for the Unicode case-folding mapping. + +@examples[ +(char-foldcase #\A) +(char-foldcase #\u03A3) +(char-foldcase #\u03c2) +(char-foldcase #\space) +]} diff --git a/collects/scribblings/reference/data.scrbl b/collects/scribblings/reference/data.scrbl index 622e4c77b4..155574b04b 100644 --- a/collects/scribblings/reference/data.scrbl +++ b/collects/scribblings/reference/data.scrbl @@ -18,8 +18,36 @@ value typically treat anything other than @scheme[#f] as true. See also: @scheme[and], @scheme[or], @scheme[andmap], @scheme[ormap]. -@defproc[(boolean? [v any/c]) boolean?]{Returns @scheme[#t] if @scheme[v] -is @scheme[#t] or @scheme[#f], @scheme[#f] otherwise.} + +@defproc[(boolean? [v any/c]) boolean?]{ + +Returns @scheme[#t] if @scheme[v] is @scheme[#t] or @scheme[#f], +@scheme[#f] otherwise.} + + +@defproc[(equal? [v1 any/c] [v2 any/c]) boolean?]{ + +Two values are @scheme[equal?] if and only if they are @scheme[eqv?], +unless otherwise specified for a particular datatype. + +Datatypes with further specification of @scheme[equal?] include strings, +byte strings, numbers, pairs, vectors, and hash tables.} + + +@defproc[(eqv? [v1 any/c] [v2 any/c]) boolean?]{ + +Two values are @scheme[eqv?] if and only if they are @scheme[eq?], +unless otherwise specified for a particular datatype. + +The number and character datatypes are the only ones for which +@scheme[eqv?] differs from @scheme[eq?].} + + +@defproc[(eq? [v1 any/c] [v2 any/c]) boolean?]{ + +Return @scheme[#t] if @scheme[v1] and @scheme[v2] refer to the same +object, @scheme[#f] otherwise. See also @secref["mz:model-eq"].} + @; ------------------------------------------------------------ @include-section["numbers.scrbl"] @@ -234,6 +262,11 @@ keys and values. See also @scheme[in-hash-table], @; ---------------------------------------------------------------------- @section[#:tag "void"]{Void and Undefined} +The constant @|void-const| is returned by most forms and procedures +that have a side-effect and no useful result. The constant +@|undefined-const| is used as the initial value for @scheme[letrec] +bindings. + @defproc[(void [v any/c] ...) void?]{Returns the constant @|void-const|. Each @scheme[v] argument is ignored.} diff --git a/collects/scribblings/reference/namespaces.scrbl b/collects/scribblings/reference/namespaces.scrbl index c38f01a33a..1eb7157c66 100644 --- a/collects/scribblings/reference/namespaces.scrbl +++ b/collects/scribblings/reference/namespaces.scrbl @@ -78,7 +78,7 @@ If @scheme[failure-thunk] is not @scheme[#f], @scheme[namespace-variable-value] calls @scheme[failure-thunk] to produce the return value in place of raising an @scheme[exn:fail:contract:variable] or @scheme[exn:fail:syntax] -exception. +exception.} @defproc[(namespace-set-variable-value! [sym symbol?] @@ -110,7 +110,7 @@ unaffected.} (listof symbol?)]{ Returns a list of all symbols that are mapped to variables, syntax, -and imports in @scheme[namespace] for @tech{phase level} 0. +and imports in @scheme[namespace] for @tech{phase level} 0.} @@ -119,23 +119,21 @@ and imports in @scheme[namespace] for @tech{phase level} 0. Performs the import corresponding to @scheme[quoted-require-spec] in the top-level environment of the current namespace, like a top-level -@scheme[require]. Module paths in -@scheme[quoted-require-spec] are resolved with respect to -@scheme[current-load-relative-directory] or @scheme[current-directory] -(if the former is @scheme[#f]), even if the current namespace -corresponds to a module body.} +@scheme[require]. The @scheme[quoted-require-spec] argument must be a +datum that corresponds to a quoted @scheme[_require-spec] for +@scheme[require]. + +Module paths in @scheme[quoted-require-spec] are resolved with respect +to @scheme[current-load-relative-directory] or +@scheme[current-directory] (if the former is @scheme[#f]), even if the +current namespace corresponds to a module body.} @defproc[(namespace-transformer-require [quoted-require-spec any/c]) void?]{ -Performs the import corresponding to @scheme[quoted-require-spec] in -the top-level transformer environment, like a top-level -@scheme[require-for-syntax]. Module paths in -@scheme[quoted-require-spec] are resolved with respect to -@scheme[current-load-relative-directory] or @scheme[current-directory] -(if the former is @scheme[#f]), even if the current namespace -corresponds to a module body.} +Like @scheme[namespace-require], but analogous to a top-level +@scheme[require-for-syntax].} @defproc[(namespace-require/copy [quoted-require-spec any/c]) @@ -149,78 +147,100 @@ value is copied to a top-level variable in the current namespace.} @defproc[(namespace-require/expansion-time [quoted-require-spec any/c]) void?]{ -Is like @scheme[namespace-require], but only the transformer part of -the module is executed; that is, the module is merely @tech{visit}ed, -and not @tech{instantiate}d (see @secref["mz:mod-parse"]). If the -required module has not been instantiated before, the module's -variables remain undefined.} +Like @scheme[namespace-require], but only the transformer part of the +module is executed; that is, the module is merely @tech{visit}ed, and +not @tech{instantiate}d (see @secref["mz:mod-parse"]). If the required +module has not been instantiated before, the module's variables remain +undefined.} @defproc[(namespace-attach-module [src-namespace namespace?] - [module-path-v any/c] - [dest-namespace any/c #f]) + [modname module-path?] + [dest-namespace namespace? (current-namespace)]) any]{ -Attaches the instantiated module named by @scheme[module-path-v] in -@scheme[src-namespace] to the registry of @scheme[dest-namespace] -(which is the current namespace if @scheme[dest-namespace] is not -supplied). If @scheme[module-path-v] is not a symbol, the current -module name resolver is called to resolve the path, but no module is -loaded; the resolved form of @scheme[module-path-v] is used as the -module name in @scheme[dest-namespace]. In addition to -@scheme[module-path-v], every module that it imports (directly or -indirectly) is also recorded in the current namespace's registry. If -@scheme[module-path-v] does not refer to an instantiated module in -@scheme[src-namespace], or if the name of any module to be attached -already has a different declaration or instance in -@scheme[dest-namespace], then the @exnraise[exn:fail:contract]. The -inspector of the module invocation in @scheme[dest-namespace] is the -same as inspector of the invocation in @scheme[src-namespace].} +Attaches the instantiated module named by @scheme[modname] in +@scheme[src-namespace] to the registry of @scheme[dest-namespace]. If +@scheme[modname] is not a symbol, the current module name resolver is +called to resolve the path, but no module is loaded; the resolved form +of @scheme[modname] is used as the module name in +@scheme[dest-namespace]. In addition to @scheme[modname], every module +that it imports (directly or indirectly) is also recorded in the +current namespace's registry. If @scheme[modname] does not refer to an +instantiated module in @scheme[src-namespace], or if the name of any +module to be attached already has a different declaration or instance +in @scheme[dest-namespace], then the @exnraise[exn:fail:contract]. +The inspector of the module invocation in @scheme[dest-namespace] is +the same as inspector of the invocation in @scheme[src-namespace].} - @defproc[(namespace-unprotect-module [inspector any/c][module-path-v any/c]) any]{namespace} - changes the inspector for the instance of the module referenced by - @scheme[module-path-v] in @scheme[namespace]'s registry so that it is - controlled by the current code inspector. If @scheme[namespace] is not - supplied, it is the current namespace. The given @scheme[inspector] must - currently control the invocation of the module in @scheme[namespace]'s - registry, otherwise the @exnraise[exn:fail:contract]. See also - @secref["mz:modprotect"]. - @defproc[(namespace-module-registry [namespace any/c]) any] returns the registry of the - given namespace. This value is useful only for identification via - @scheme[eq?]. +@defproc[(namespace-unprotect-module [inspector inspector?] + [modname module-path?] + [namespace namespace? (current-namespace)]) + void?]{ - @defproc[(module->namespace [module-path-v any/c]) any] returns a namespace that - corresponds to the body of an instantiated module in the current - namespace's registry. The returned namespace has the same module - registry as the current namespace. Modifying a binding in the - namespace changes the binding seen in modules that require the - namespace's module. Module paths in a top-level @scheme[require] - expression are resolved with respect to the namespace's module. New - @scheme[provide] declarations are not allowed. If the current code - inspector does not control the invocation of the module in the - current namespace's registry, the @exnraise[exn:fail:contract]; see - also @secref["mz:modprotect"]. Bindings in the namespace cannot be - modified if the @scheme[compile-enforce-module-constants] parameter - was true when the module was declared, unless the module declaration - itself included assignments to the binding via @scheme[set!]. +Changes the inspector for the instance of the module referenced by +@scheme[modname] in @scheme[namespace]'s registry so that it is +controlled by the current code inspector. The given @scheme[inspector] +must currently control the invocation of the module in +@scheme[namespace]'s registry, otherwise the +@exnraise[exn:fail:contract]. See also @secref["mz:modprotect"].} - @defproc[(namespace-syntax-introduce [stx any/c]) any] returns a syntax object like - @scheme[stx], except that the current namespace's bindings are included - in the syntax object's context (see @secref["mz:stxscope"]). The - additional context is overridden by any existing top-level context in - the syntax object, or by any existing or future module context. See - @secref["mz:stxobj"] for more information about syntax objects. - @defproc[(module-provide-protected? [module-path-index any/c][sym symbol?]) any] returns - @scheme[#f] if the module declaration for @scheme[module-path-index] - defines @scheme[sym] and exports it unprotected, @scheme[#t] - otherwise (which may mean that the symbol corresponds to an - unexported definition, a protected export, or an identifier that is - not defined at all within the module). The @scheme[module-path-index] - argument can be a symbol; see @secref["mz:modpathidx"] for more information - on module path indices. Typically, the arguments to - @scheme[module-provide-protected?] correspond to the first two - elements of a list produced by @scheme[identifier-binding] (see - @secref["mz:stxscope"]). +@defproc[(namespace-module-registry [namespace namespace?]) + any]{ +Returns the registry of the given namespace. This value is useful only +for identification via @scheme[eq?].} + + +@defproc[(module->namespace [modname module-path?]) namespace?]{ + +Returns a namespace that corresponds to the body of an instantiated +module in the current namespace's registry. The returned namespace has +the same module registry as the current namespace. Modifying a binding +in the namespace changes the binding seen in modules that require the +namespace's module. + +Module paths in a top-level @scheme[require] expression are resolved +with respect to the namespace's module. New @scheme[provide] +declarations are not allowed. + +If the current code inspector does not control the invocation of the +module in the current namespace's registry, the +@exnraise[exn:fail:contract]; see also +@secref["mz:modprotect"]. + +Bindings in the namespace cannot be modified if the +@scheme[compile-enforce-module-constants] parameter was true when the +module was declared, unless the module declaration itself included +assignments to the binding via @scheme[set!].} + + +@defproc[(namespace-syntax-introduce [stx syntax-object?]) syntax-object?]{ + +Returns a syntax object like @scheme[stx], except that the current +namespace's bindings are included in the syntax object's context (see +@secref["mz:stxscope"]). The additional context is overridden by any +existing top-level context in the syntax object, or by any existing or +future module context. See @secref["mz:stxobj"] for more information +about syntax objects.} + + +@defproc[(module-provide-protected? [module-path-index (or/c symbol? module-path-index?)] + [sym symbol?]) + boolean?]{ + +Returns @scheme[#f] if the module declaration for +@scheme[module-path-index] defines @scheme[sym] and exports it +unprotected, @scheme[#t] otherwise (which may mean that the symbol +corresponds to an unexported definition, a protected export, or an +identifier that is not defined at all within the module). + +The @scheme[module-path-index] argument can be a symbol; see +@secref["mz:modpathidx"] for more information on module path +indices. + +Typically, the arguments to @scheme[module-provide-protected?] +correspond to the first two elements of a list produced by +@scheme[identifier-binding] (see @secref["mz:stxscope"]).} diff --git a/collects/scribblings/reference/numbers.scrbl b/collects/scribblings/reference/numbers.scrbl index ce85f656c8..38370e4b7a 100644 --- a/collects/scribblings/reference/numbers.scrbl +++ b/collects/scribblings/reference/numbers.scrbl @@ -528,6 +528,75 @@ noted above). Two numbers are @scheme[equal?] when they are @examples[(integer-length 8) (integer-length -8)]} +@; ------------------------------------------------------------------------ +@section{Random Numbers} + +@defproc*[([(random [k (and positive-exact-integer? + (integer-in 1 (sub1 (expt 2 31))))]) + nonnegative-exact-integer?] + [(random) (and real? inexact? (>/c 0) (vector [generator pseudo-random-generator?]) + vector?]{ + +Produces a vector that represents the complete internal state of +@scheme[generator]. The vector is suitable as an argument to +@scheme[vector->pseudo-random-generator] to recreate the generator in +its current state (across runs and across platforms).} + + +@defproc[(vector->pseudo-random-generator [vec vector?]) + pseudo-random-generator?]{ + +Produces a pseudo-random number generator whose internal state +corresponds to @scheme[vec]. The vector @scheme[vec] must contain six +exact integers; the first three integers must be in the range +@scheme[0] to @scheme[4294967086], inclusive; the last three integers +must be in the range @scheme[0] to @scheme[4294944442], inclusive; at +least one of the first three integers must be non-zero; and at least +one of the last three integers must be non-zero.} + @; ------------------------------------------------------------------------ @section{Number--String Conversions} @@ -552,3 +621,87 @@ noted above). Two numbers are @scheme[equal?] when they are @examples[(string->number "3.0+2.5i") (string->number "hello") (string->number "111" 7) (string->number "#b111" 7)] } + + +@defproc[(integer-bytes->integer [bstr bytes?] + [signed? any/c] + [big-endian? any/c (system-big-endian?)]) + exact-integer?]{ + +Converts the machine-format number encoded in @scheme[bstr] to an +exact integer. The @scheme[bstr] must contain either 2, 4, or 8 +bytes. If @scheme[signed?] is true, then the bytes are decoded as a +two's-complement number, otherwise it is decoded as an unsigned +integer. If @scheme[big-endian?] is true, then the first character's +ASCII value provides the most significant eight bits of the number, +otherwise the first character provides the least-significant eight +bits, and so on..} + + +@defproc[(integer->integer-bytes [n exact-integer?] + [size-n (one-of/c 2 4 8)] + [signed? any/c] + [big-endian? any/c (system-big-endian?)] + [dest-bstr (and bytes? + (not/c immutable?)) + (make-bytes size-n)]) + bytes?]{ + +Converts the exact integer @scheme[n] to a machine-format number +encoded in a byte string of length @scheme[size-n], which must be 2, +4, or 8. If @scheme[signed?] is true, then the number is encoded as +two's complement, otherwise it is encoded as an unsigned bit +stream. If @scheme[big-endian?] is true, then the most significant +eight bits of the number are encoded in the first character of the +resulting byte string, otherwise the least-significant bits are +encoded in the first byte, and so on. + +The @scheme[dest-bstr] argument must be a mutable byte string of +length @scheme[size-n]. The encoding of @scheme[n] is written into +@scheme[dest-bstr], and @scheme[dest-bstr] is returned as the result. + +If @scheme[n] cannot be encoded in a string of the requested size and +format, the @exnraise[exn:fail:contract]. If @scheme[dest-bstr] is not +of length @scheme[size-n], the @exnraise[exn:fail:contract].} + + +@defproc[(floating-point-bytes->real [bstr bytes?] + [big-endian? any/c (system-big-endian?)]) + (and real? inexact?)]{ + +Converts the IEEE floating-point number encoded in @scheme[bstr] to an +inexact real number. The @scheme[bstr] must contain either 4 or 8 +bytes. If @scheme[big-endian?] is true, then the first byte's ASCII +value provides the most significant eight bits of the IEEE +representation, otherwise the first byte provides the +least-significant eight bits, and so on.} + + +@defproc[(real->floating-point-bytes [x real?] + [size-n (one-of/c 4 8)] + [big-endian? any/c (system-big-endian?)] + [dest-bstr (and bytes? + (not/c immutable?)) + (make-bytes size-n)]) + bytes?]{ + +Converts the real number @scheme[x] to its IEEE representation in a +byte string of length @scheme[size-n], which must be 4 or 8. If +@scheme[big-endian?] is true, then the most significant eight bits of +the number are encoded in the first byte of the resulting byte string, +otherwise the least-significant bits are encoded in the first +character, and so on. + +The @scheme[dest-bstr] argument must be a mutable byte string of +length @scheme[size-n]. The encoding of @scheme[n] is written into +@scheme[dest-bstr], and @scheme[dest-bstr] is returned as the result. + +If @scheme[dest-bstr] is provided and it is not of length +@scheme[size-n], the @exnraise[exn:fail:contract].} + + +@defproc[(system-big-endian?) boolean?]{ + +Returns @scheme[#t] if the native encoding of numbers is big-endian +for the machine running Scheme, @scheme[#f] if the native encoding +is little-endian.} diff --git a/collects/scribblings/reference/security.scrbl b/collects/scribblings/reference/security.scrbl index 4462a098f9..3defe9e456 100644 --- a/collects/scribblings/reference/security.scrbl +++ b/collects/scribblings/reference/security.scrbl @@ -15,4 +15,4 @@ which relies on @tech{thread}- and @tech{continuation}-specific @include-section["thread-groups.scrbl"] @include-section["struct-inspectors.scrbl"] @include-section["code-inspectors.scrbl"] -@; @include-section["namespaces.scrbl"] +@include-section["namespaces.scrbl"] diff --git a/collects/scribblings/reference/strings.scrbl b/collects/scribblings/reference/strings.scrbl index 99615affab..6071183c3c 100644 --- a/collects/scribblings/reference/strings.scrbl +++ b/collects/scribblings/reference/strings.scrbl @@ -15,9 +15,8 @@ procedure like @scheme[string-set!], the default reader (see @secref["mz:parse-string"]) are immutable. -Two strings are @scheme[eq?] when mutating one would mutate the other. -Two strings are @scheme[eqv?] and @scheme[equal?] when they have the -same length and contain the same sequence of characters. +Two strings are @scheme[equal?] when they have the same length and +contain the same sequence of characters. A string can be used as a single-valued sequence (see @secref["mz:sequences"]). The characters of the string serve as elements @@ -164,7 +163,7 @@ Returns an immutable string with the same content as @defproc[(string=? [str1 string?] [str2 string?] ...+) boolean?]{ Returns - @scheme[#t] if all of the arguments are @scheme[eqv?].} + @scheme[#t] if all of the arguments are @scheme[equal?].} @examples[(string=? "Apple" "apple") (string=? "a" "as" "a")] diff --git a/collects/scribblings/scribble/doclang.scrbl b/collects/scribblings/scribble/doclang.scrbl index 9af8c51be5..f23530c6fa 100644 --- a/collects/scribblings/scribble/doclang.scrbl +++ b/collects/scribblings/scribble/doclang.scrbl @@ -2,7 +2,7 @@ @require[(lib "manual.ss" "scribble")] @require["utils.ss"] -@title[#:tag "doclang"]{Document Module Languegs} +@title[#:tag "doclang"]{Document Module Language} The @file{doclang.ss} module is suitable for use as a module language. It provides everything from @scheme[mzscheme], except that