Merge branch 'master' of git://factorcode.org/git/factor

basis/help/markup/markup.factor

@@ -181,20 +181,22 @@ M: word link-long-text
 
 : >topic ( obj -- topic ) dup topic? [ >link ] unless ;
 
+: topic-span ( topic quot -- ) [ >topic ] dip ($span) ; inline
+
 PRIVATE>
 
-: ($link) ( topic -- ) >topic link-text ;
+: ($link) ( topic -- ) [ link-text ] topic-span ;
 : $link ( element -- ) first ($link) ;
 
-: ($long-link) ( topic -- ) >topic link-long-text ;
+: ($long-link) ( topic -- ) [ link-long-text ] topic-span ;
 : $long-link ( element -- ) first ($long-link) ;
 
 : ($pretty-link) ( topic -- )
-    >topic [ link-icon ] [ drop bl ] [ link-text ] tri ;
+    [ [ link-icon ] [ drop bl ] [ link-text ] tri ] topic-span ;
 : $pretty-link ( element -- ) first ($pretty-link) ;
 
 : ($long-pretty-link) ( topic -- )
-    >topic [ link-icon ] [ drop bl ] [ link-long-text ] tri ;
+    [ [ link-icon ] [ drop bl ] [ link-long-text ] tri ] topic-span ;
 
 : <$pretty-link> ( definition -- element )
     1array \ $pretty-link prefix ;

basis/random/dummy/dummy-tests.factor

@@ -0,0 +1,7 @@
+! Copyright (C) 2009 Doug Coleman.
+! See http://factorcode.org/license.txt for BSD license.
+USING: random random.dummy tools.test ;
+IN: random.dummy.tests
+
+[ 10 ] [ 10 <random-dummy> random-32* ] unit-test
+[ 100 ] [ 10 <random-dummy> 100 seed-random random-32* ] unit-test

basis/random/dummy/dummy.factor

@@ -4,8 +4,8 @@ IN: random.dummy
 TUPLE: random-dummy i ;
 C: <random-dummy> random-dummy
 
-M: random-dummy seed-random ( seed obj -- )
-    (>>i) ;
+M: random-dummy seed-random ( obj seed -- obj )
+    >>i ;
 
 M: random-dummy random-32* ( obj -- r )
     [ dup 1 + ] change-i drop ;

basis/random/mersenne-twister/mersenne-twister-tests.factor

@@ -27,3 +27,9 @@ IN: random.mersenne-twister.tests
 [ 3 ] [ 101 [ 3 random-bytes length ] test-rng ] unit-test
 [ 33 ] [ 101 [ 33 random-bytes length ] test-rng ] unit-test
 [ t ] [ 101 [ 100 random-bits log2 90 > ] test-rng ] unit-test
+
+[ t ]
+[
+    1234 <mersenne-twister>
+    [ random-32* ] [ 1234 seed-random random-32* ] bi =
+] unit-test

basis/random/mersenne-twister/mersenne-twister.factor

@@ -62,15 +62,21 @@ PRIVATE>
     init-mt-seq 0 mersenne-twister boa
     dup mt-generate ;
 
-M: mersenne-twister seed-random ( mt seed -- )
-    init-mt-seq >>seq drop ;
+M: mersenne-twister seed-random ( mt seed -- mt' )
+    init-mt-seq >>seq
+    [ mt-generate ]
+    [ 0 >>i drop ]
+    [ ] tri ;
 
 M: mersenne-twister random-32* ( mt -- r )
     [ next-index ]
     [ seq>> nth-unsafe mt-temper ]
     [ [ 1 + ] change-i drop ] tri ;
 
-[
+: default-mersenne-twister ( -- mersenne-twister )
     [ 32 random-bits ] with-system-random
-    <mersenne-twister> random-generator set-global
+    <mersenne-twister> ;
+
+[
+    default-mersenne-twister random-generator set-global
 ] "bootstrap.random" add-init-hook

basis/random/random-docs.factor

@@ -2,8 +2,12 @@ USING: help.markup help.syntax math kernel sequences ;
 IN: random
 
 HELP: seed-random
-{ $values { "tuple" "a random number generator" } { "seed" "an integer between 0 and 2^32-1" } }
-{ $description "Seed the random number generator." }
+{ $values
+    { "tuple" "a random number generator" }
+    { "seed" "a seed specific to the random number generator" }
+    { "tuple'" "a random number generator" }
+}
+{ $description "Seed the random number generator. Repeatedly seeding the random number generator should provide the same sequence of random numbers." }
 { $notes "Not supported on all random number generators." } ;
 
 HELP: random-32*
@@ -29,6 +33,10 @@ HELP: random
         "heads" }
 } ;
 
+HELP: random-32
+{ $values { "elt" "a 32-bit random integer" } }
+{ $description "Outputs 32 random bits. This word is more efficient than calling " { $link random } " because no scaling is done on the output." } ;
+
 HELP: random-bytes
 { $values { "n" "an integer" } { "byte-array" "a random integer" } }
 { $description "Outputs an integer with n bytes worth of bits." }
@@ -104,6 +112,8 @@ $nl
 $nl
 "Generate a random object:"
 { $subsection random }
+"Efficient 32-bit random numbers:"
+{ $subsection random-32 }
 "Combinators to change the random number generator:"
 { $subsection with-random }
 { $subsection with-system-random }

basis/random/random.factor

@@ -10,7 +10,7 @@ SYMBOL: system-random-generator
 SYMBOL: secure-random-generator
 SYMBOL: random-generator
 
-GENERIC: seed-random ( tuple seed -- )
+GENERIC# seed-random 1 ( tuple seed -- tuple' )
 GENERIC: random-32* ( tuple -- r )
 GENERIC: random-bytes* ( n tuple -- byte-array )
 
@@ -55,6 +55,8 @@ PRIVATE>
         [ length random-integer ] keep nth
     ] if-empty ;
 
+: random-32 ( -- n ) random-generator get random-32* ;
+
 : randomize ( seq -- seq )
     dup length [ dup 1 > ]
     [ [ iota random ] [ 1 - ] bi [ pick exchange ] keep ]

core/checksums/checksums-docs.factor

@@ -20,15 +20,39 @@ HELP: checksum-stream
 
 HELP: checksum-bytes
 { $values { "bytes" "a sequence of bytes" } { "checksum" "a checksum specifier" } { "value" byte-array } }
-{ $contract "Computes the checksum of all data in a sequence." } ;
+{ $contract "Computes the checksum of all data in a sequence." }
+{ $examples
+    { $example
+        "USING: checksums checksums.crc32 prettyprint ;"
+        "B{ 1 10 100 } crc32 checksum-bytes ."
+        "B{ 78 179 254 238 }"
+    }
+} ;
 
 HELP: checksum-lines
 { $values { "lines" "a sequence of sequences of bytes" } { "checksum" "a checksum specifier" } { "value" byte-array } }
-{ $contract "Computes the checksum of all data in a sequence." } ;
+{ $contract "Computes the checksum of all data in a sequence." }
+{ $examples
+    { $example
+        "USING: checksums checksums.crc32 prettyprint ;"
+"""{
+    "Take me out to the ball game"
+    "Take me out with the crowd"
+} crc32 checksum-lines ."""
+        "B{ 111 205 9 27 }"
+    }
+} ;
 
 HELP: checksum-file
 { $values { "path" "a pathname specifier" } { "checksum" "a checksum specifier" } { "value" byte-array } }
-{ $contract "Computes the checksum of all data in a file." } ;
+{ $contract "Computes the checksum of all data in a file." }
+{ $examples
+    { $example
+        "USING: checksums checksums.crc32 prettyprint ;"
+        """"resource:license.txt" crc32 checksum-file ."""
+        "B{ 100 139 199 92 }"
+    }
+} ;
 
 ARTICLE: "checksums" "Checksums"
 "A " { $emphasis "checksum" } " is a function mapping sequences of bytes to fixed-length strings. While checksums are not one-to-one, a good checksum should have a low probability of collision. Additionally, some checksum algorithms are designed to be hard to reverse, in the sense that finding an input string which hashes to a given checksum string requires a brute-force search."