Documentation updates -- most primitives now documented

library/bootstrap/boot-stage1.factor

@@ -233,6 +233,7 @@ vectors words ;
         "/library/compiler/alien/malloc.facts"
         "/library/compiler/alien/structs.facts"
         "/library/compiler/alien/syntax.facts"
+        "/library/compiler/generator/assembler.facts"
         "/library/compiler/inference/inference.facts"
         "/library/compiler/compiler.facts"
         "/library/generic/early-generic.facts"

library/collections/arrays.facts

@@ -30,3 +30,7 @@ HELP: 3array "( x y z -- array )"
 { $values { "x" "an object" } { "y" "an object" } { "z" "an object" } { "array" "an array" } }
 { $description "Create a new array with three elements." }
 { $see-also 1array 2array ch>string } ;
+
+HELP: resize-array "( n array -- newarray )"
+{ $values { "n" "a non-negative integer" } { "array" "an array" } { "newarray" "a new array" } }
+{ $description "Creates a new array of " { $snippet "n" } " elements. The contents of the existing array are copied into the new array; if the new array is shorter, only an initial segment is copied, and if the new array is longer the remaining space is filled in with "{ $link f } "." } ;

library/collections/hashtables.facts

@@ -98,6 +98,10 @@ HELP: <hashtable> "( n -- hash )"
 { $description "Create a new hashtable capable of storing " { $snippet "n" } " key/value pairs before growing." }
 { $see-also clear-hash hash-size hash-empty? } ;
 
+HELP: (hashtable) "( -- hash )"
+{ $values { "hash" "a new hashtable" } }
+{ $description "Allocates a hashtable stub object without an underlying array. User code should call " { $link <hashtable> } " instead." } ;
+
 HELP: associate "( value key -- hash )"
 { $values { "value" "a value" } { "key" "a key" } }
 { $description "Create a new hashtable holding one key/value pair." } ;

library/collections/sequences.facts

@@ -13,7 +13,7 @@ HELP: set-length "( n seq -- )"
 { $side-effects "seq" } ;
 
 HELP: nth "( n seq -- elt )"
-{ $values { "n" "a non-negative integer" } { "seq" "a sequence" } }
+{ $values { "n" "a non-negative integer" } { "seq" "a sequence" } { "elt" "the element at the " { $snippet "n" } "th index" } }
 { $contract "Outputs the " { $snippet "n" } "th element of the sequence. Elements are numbered from zero, so the last element has an index one less than the length of the sequence. All sequences support this operation."
 $terpri
 "This generic word is flushable, so user-defined methods must satisfy the flushable contract (see " { $link "declarations" } ")." }

library/collections/strings.facts

@@ -1,4 +1,15 @@
-USING: arrays help kernel strings vectors ;
+USING: arrays help kernel kernel-internals sequences strings
+vectors ;
+
+HELP: char-slot "( n string -- ch )"
+{ $values { "n" "a fixnum" } { "string" "a string" } { "ch" "the character at the " { $snippet "n" } "th index" } }
+{ $description "Unsafe string accessor, used to define " { $link nth } " on strings." }
+{ $warning "This word is in the " { $snippet "kernel-internals" } " vocabulary because it does not perform type or bounds checking. User code should call " { $link nth } " instead." } ;
+
+HELP: set-char-slot "( ch n string -- )"
+{ $values { "ch" "a character" } { "n" "a fixnum" } { "string" "a string" }  }
+{ $description "Unsafe string mutator, used to define " { $link set-nth } " on strings." }
+{ $warning "This word is in the " { $snippet "kernel-internals" } " vocabulary because it does not perform type or bounds checking. User code should call " { $link set-nth } " instead." } ;
 
 HELP: <string> "( n ch -- string )"
 { $values { "n" "a positive integer specifying string length" } { "elt" "an initial character" } }
@@ -72,3 +83,7 @@ HELP: >string "( seq -- str )"
 { $description "Outputs a freshly-allocated string with the same elements as a given sequence." }
 { $errors "Throws an error if the sequence contains elements other than real numbers." }
 { $see-also >array >sbuf >vector >quotation } ;
+
+HELP: resize-string "( n str -- newstr )"
+{ $values { "n" "a non-negative integer" } { "str" "a string" } { "newstr" "a new string" } }
+{ $description "Creates a new string " { $snippet "n" } " characters long The contents of the existing string are copied into the new string; if the new string is shorter, only an initial segment is copied, and if the new string is longer the remaining space is filled with " { $snippet "\u0000" } "." } ;

library/compiler/compiler.facts

@@ -1,5 +1,5 @@
 IN: compiler
-USING: help words ;
+USING: assembler help words ;
 
 HELP: compiled? "( word -- ? )"
 { $values { "word" "a word" } }

library/compiler/generator/assembler.facts

@@ -0,0 +1,21 @@
+IN: assembler
+USING: help ;
+
+HELP: compiled-offset "( -- n )"
+{ $values { "n" "an address" } }
+{ $description "Outputs the pointer to the top of the code heap where new code can be compiled." } ;
+
+HELP: set-compiled-offset "( n -- )"
+{ $values { "n" "an address" } }
+{ $description "Sets the pointer to the top of the code heap where new code can be compiled." } ;
+
+HELP: literal-top "( -- n )"
+{ $values { "n" "an address" } }
+{ $description "Outputs a pointer to the top of the literal data area. The compiler deposits references made to heap-allocated objects from compiled code in this area." } ;
+
+HELP: set-literal-top "( -- n )"
+{ $values { "n" "an address" } }
+{ $description "Sets the pointer to the top of the literal data area. The compiler deposits references made to heap-allocated objects from compiled code in this area." } ;
+
+HELP: flush-icache "( -- )"
+{ $description "Flushes the CPUs instruction cache on PowerPC, and does nothing on other architectures. PowerPC CPUs do not automatically invalidate the cache when memory contents change, so the compiler must do this explicitly." } ;

library/compiler/inference/known-words.factor

@@ -467,8 +467,8 @@ sequences strings vectors words prettyprint ;
 \ char-slot t "flushable" set-word-prop
 
 \ set-char-slot [ [ fixnum fixnum object ] [ ] ] "infer-effect" set-word-prop
-\ resize-array [ [ fixnum array ] [ array ] ] "infer-effect" set-word-prop
-\ resize-string [ [ fixnum string ] [ string ] ] "infer-effect" set-word-prop
+\ resize-array [ [ integer array ] [ array ] ] "infer-effect" set-word-prop
+\ resize-string [ [ integer string ] [ string ] ] "infer-effect" set-word-prop
 
 \ (hashtable) [ [ ] [ hashtable ] ] "infer-effect" set-word-prop
 \ (hashtable) t "flushable" set-word-prop

library/io/c-streams.facts

@@ -38,3 +38,33 @@ $terpri
 "The client socket supports two accessor words to get the host name and port number of the incoming connection:"
 { $list { $link client-stream-host } { $link client-stream-port } } }
 { $errors "Throws an error if the server socket is closed or otherwise is unavailable." } ;
+
+HELP: <c-stream> "( in out -- stream )"
+{ $values { "in" "a C FILE* handle" } { "out" "a C FILE* handle" } }
+{ $description "Creates a stream which reads and writes data by calling C standard library functions." }
+{ $notes "Usually C streams are only used during bootstrap, and non-blocking OS-specific I/O routines are used during normal operation." } ;
+
+HELP: fopen "( path mode -- alien )"
+{ $values { "path" "a pathname string" } { "mode" "an access mode specifier" } { "alien" "a C FILE* handle" } }
+{ $description "Opens a file named by " { $snippet "path" } ". The " { $snippet "mode" } " parameter should be something like " { $snippet "\"r\"" } " or " { $snippet "\"rw\"" } "; consult the " { $snippet "fopen(3)" } " manual page for details." }
+{ $errors "Throws an error if the file could not be opened." }
+{ $notes "User code should call " { $link <file-reader> } " or " { $link <file-writer> } " to get a high level stream." } ;
+
+HELP: fwrite "( string alien -- )"
+{ $values { "string" "a string" } { "alien" "a C FILE* handle" } }
+{ $description "Writes a string of text to a C FILE* handle." }
+{ $errors "Throws an error if the output operation failed." } ;
+
+HELP: fflush "( alien -- )"
+{ $values { "alien" "a C FILE* handle" } }
+{ $description "Forces pending output on a C FILE* handle to complete." }
+{ $errors "Throws an error if the output operation failed." } ;
+
+HELP: fclose "( alien -- )"
+{ $values { "alien" "a C FILE* handle" } }
+{ $description "Closes a C FILE* handle." } ;
+
+HELP: fgetc "( alien -- ch )"
+{ $values { "alien" "a C FILE* handle" } { "ch" "a character" } }
+{ $description "Reads a single character from a C FILE* handle." } 
+{ $errors "Throws an error if the input operation failed." } ;

library/io/files.facts

@@ -1,13 +1,23 @@
 USING: help io ;
 
-HELP: stat "( path -- list )"
-{ $values { "path" "a pathname string" } { "list" "a new list" } }
+HELP: cwd "( -- path )"
+{ $values { "path" "a pathname string" } }
+{ $description "Outputs the current working directory of the Factor process." }
+{ $see-also cd } ;
+
+HELP: cd "( path -- )"
+{ $values { "path" "a pathname string" } }
+{ $description "Changes the current working directory of the Factor process." }
+{ $see-also cwd } ;
+
+HELP: stat "( path -- array/f )"
+{ $values { "path" "a pathname string" } { "array/f" "a four-element array or " { $link f } } }
 { $description
-    "Outputs a list of file system attributes, or " { $link f } " if the file does not exist. The elements of the list are precisely the following:"
+    "If the file does not exist, outputs " { $link f } ". Otherwise, outputs a four-element array:"
     { $list
         "boolean indicating if the file is a directory"
         "the length in bytes as an integer"
-        "a Unix permission bitmap, or 0 if not supported"
+        "a Unix permission bitmap (0 on Windows)"
         "the last modification time, as milliseconds since midnight, January 1st 1970 GMT"
     }
 } ;

library/kernel.facts

@@ -1,5 +1,5 @@
 USING: generic help kernel kernel-internals math memory
-sequences ;
+namespaces sequences ;
 
 HELP: eq? "( obj1 obj2 -- ? )"
 { $values { "obj1" "an object" } { "obj2" "an object" } }
@@ -120,8 +120,13 @@ HELP: num-types "( -- n )"
 
 HELP: type "( object -- n )"
 { $values { "object" "an object" } { "n" "a type number" } }
-{ $description "Outputs an object's type number. Often, the " { $link class } " word is more useful." }
-{ $see-also type>class } ;
+{ $description "Outputs an object's type number, between zero and one less than " { $link num-types } ". This is implementation detail and user code should call " { $link class } " instead." }
+{ $see-also type>class tag } ;
+
+HELP: tag "( object -- n )"
+{ $values { "object" "an object" } { "n" "a tag number" } }
+{ $description "Outputs an object's tag number, between zero and one less than " { $link num-tags } ". This is implementation detail and user code should call " { $link class } " instead." }
+{ $see-also type } ;
 
 HELP: ? "( cond true false -- true/false )"
 { $values { "cond" "a generalized boolean" } { "true" "an object" } { "false" "an object" } { "true/false" "one two input objects" } }
@@ -305,3 +310,55 @@ HELP: save-image "( path -- )"
 
 HELP: save "( -- )"
 { $description "Saves a snapshot of the heap to the current image file." } ;
+
+HELP: die "( -- )"
+{ $description "Starts the front-end processor (FEP), which is a low-level debugger which can inspect memory addresses and the like. The FEP is also entered when a critical error occurs." } ;
+
+HELP: exit "( n -- )"
+{ $values { "n" "an integer exit code" } }
+{ $description "Exits the Factor process." } ;
+
+HELP: getenv "( n -- obj )"
+{ $values { "n" "a non-negative integer" } { "obj" "an object" } }
+{ $values "Reads an object from the Factor runtime's environment table. User code never has to read the environment table directly; instead, use one of the callers of this word." } ;
+
+HELP: setenv "( obj n -- )"
+{ $values { "n" "a non-negative integer" } { "obj" "an object" } }
+{ $values "Writes an object to the Factor runtime's environment table. User code never has to write to the environment table directly; instead, use one of the callers of this word." } ;
+
+HELP: integer-slot "( obj m -- n )"
+{ $values { "obj" "an object" } { "m" "a non-negative fixnum" } { "n" "an integer" } }
+{ $description "Reads the untagged integer stored at the " { $snippet "n" } "th slot of " { $snippet "obj" } "." }
+{ $warning "This word is in the " { $snippet "kernel-internals" } " vocabulary because it does not perform type or bounds checks, and slot numbers are implementation detail." } ;
+
+HELP: set-integer-slot "( m obj n -- )"
+{ $values { "n" "an integer" }  { "obj" "an object" } { "m" "a non-negative fixnum" } }
+{ $description "Writes an untagged integer to the " { $snippet "n" } "th slot of " { $snippet "obj" } "." }
+{ $warning "This word is in the " { $snippet "kernel-internals" } " vocabulary because it does not perform type or bounds checks, and slot numbers are implementation detail." } ;
+
+HELP: slot "( obj m -- value )"
+{ $values { "obj" "an object" } { "m" "a non-negative fixnum" } { "value" "an object" } }
+{ $description "Reads the object stored at the " { $snippet "n" } "th slot of " { $snippet "obj" } "." }
+{ $warning "This word is in the " { $snippet "kernel-internals" } " vocabulary because it does not perform type or bounds checks, and slot numbers are implementation detail." } ;
+
+HELP: set-slot "( value obj n -- )"
+{ $values { "value" "an object" } { "obj" "an object" } { "m" "a non-negative fixnum" } }
+{ $description "Writes " { $snippet "value" } " to the " { $snippet "n" } "th slot of " { $snippet "obj" } "." }
+{ $warning "This word is in the " { $snippet "kernel-internals" } " vocabulary because it does not perform type or bounds checks, and slot numbers are implementation detail." } ;
+
+HELP: millis "( -- n )"
+{ $values { "n" "an integer" } }
+{ $description "Outputs the number of milliseconds ellapsed since midnight January 1, 1970." } ;
+
+HELP: os-env "( key -- value )"
+{ $values { "key" "a string" } { "value" "a string" } }
+{ $description "Looks up the value of a shell environment variable." }
+{ $examples 
+    "This is an operating system-specific feature. On Unix, you can do:"
+    { $example "\"USER\" os-env print" "slava" }
+} ;
+
+HELP: dispatch "( n array -- )"
+{ $values { "n" "a fixnum" } { "array" "an array of quotations" } }
+{ $description "Calls the " { $snippet "n" } "th quotation in the array." }
+{ $warning "This word is in the " { $snippet "kernel-internals" } " vocabulary because it is an implementation detail used by the generic word system to accelerate method dispatch. It does not perform type or bounds checks, and user code should not need to call it directly." } ;

library/math/float.facts

@@ -1,4 +1,4 @@
-USING: help math ;
+USING: help math math-internals ;
 
 HELP: float f
 { $description "The class of double-precision floating point numbers." } ;
@@ -6,3 +6,69 @@ HELP: float f
 HELP: >float "( x -- y )"
 { $values { "x" "a real number" } { "y" "a float" } }
 { $description "Converts a real to a float. This is the identity on floats, and performs a floating point division on rationals." } ;
+
+HELP: bits>double "( n -- x )"
+{ $values { "n" "a 64-bit integer representing an 754 double-precision float" } { "x" "a float" } }
+{ $description "Creates a " { $link float } " object from a binary representation. This word is usually used to reconstruct floats read from streams." }
+{ $see-also bits>float double>bits float>bits } ;
+
+HELP: bits>float "( n -- x )"
+{ $values { "n" "a 32-bit integer representing an 754 single-precision float" } { "x" "a float" } }
+{ $description "Creates a " { $link float } " object from a binary representation. This word is usually used to reconstruct floats read from streams." }
+{ $see-also bits>double double>bits float>bits } ;
+
+HELP: double>bits "( x -- n )"
+{ $values { "x" "a float" } { "n" "a 64-bit integer representing an 754 double-precision float" } }
+{ $description "Creates a " { $link float } " object from a binary representation. This word is usually used to reconstruct floats read from streams." }
+{ $see-also bits>double bits>float float>bits } ;
+
+HELP: float>bits "( x -- n )"
+{ $values { "x" "a float" } { "n" "a 32-bit integer representing an 754 single-precision float" } }
+{ $description "Creates a " { $link float } " object from a binary representation. This word is usually used to reconstruct floats read from streams." }
+{ $see-also bits>double bits>float double>bits } ;
+
+! Unsafe primitives
+HELP: float+ "( x y -- z )"
+{ $values { "x" "a float" } { "y" "a float" } { "z" "a float" } }
+{ $description "Primitive version of " { $link + } "." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link + } " instead." } ;
+
+HELP: float- "( x y -- z )"
+{ $values { "x" "a float" } { "y" "a float" } { "z" "a float" } }
+{ $description "Primitive version of " { $link - } "." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link - } " instead." } ;
+
+HELP: float* "( x y -- z )"
+{ $values { "x" "a float" } { "y" "a float" } { "z" "a float" } }
+{ $description "Primitive version of " { $link * } "." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link * } " instead." } ;
+
+HELP: float-mod "( x y -- z )"
+{ $values { "x" "a float" } { "y" "a float" } { "z" "a float" } }
+{ $description "Primitive version of " { $link mod } "." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link mod } " instead." } ;
+
+HELP: float/f "( x y -- z )"
+{ $values { "x" "a float" } { "y" "a float" } { "z" "a float" } }
+{ $description "Primitive version of " { $link /f } "." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link /f } " instead." } ;
+
+HELP: float< "( x y -- ? )"
+{ $values { "x" "a float" } { "y" "a float" } { "?" "a boolean" } }
+{ $description "Primitive version of " { $link < } "." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link < } " instead." } ;
+
+HELP: float<= "( x y -- ? )"
+{ $values { "x" "a float" } { "y" "a float" } { "?" "a boolean" } }
+{ $description "Primitive version of " { $link <= } "." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link <= } " instead." } ;
+
+HELP: float> "( x y -- ? )"
+{ $values { "x" "a float" } { "y" "a float" } { "?" "a boolean" } }
+{ $description "Primitive version of " { $link > } "." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link > } " instead." } ;
+
+HELP: float>= "( x y -- ? )"
+{ $values { "x" "a float" } { "y" "a float" } { "?" "a boolean" } }
+{ $description "Primitive version of " { $link >= } "." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link >= } " instead." } ;

library/math/integer.facts

@@ -39,6 +39,96 @@ HELP: fraction> "( a b -- a/b )"
 { $description "Creates a new ratio, or outputs the numerator if the denominator is 1. This word does not reduce the fraction to lowest terms, and should not be called directly; use " { $link / } " instead." } ;
 
 ! Unsafe primitives
+HELP: fixnum+ "( x y -- z )"
+{ $values { "x" "a fixnum" } { "y" "a fixnum" } { "z" "an integer" } }
+{ $description "Primitive version of " { $link + } ". The result may overflow to a bignum." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link + } " instead." } ;
+
+HELP: fixnum- "( x y -- z )"
+{ $values { "x" "a fixnum" } { "y" "a fixnum" } { "z" "an integer" } }
+{ $description "Primitive version of " { $link - } ". The result may overflow to a bignum." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link - } " instead." } ;
+
+HELP: fixnum* "( x y -- z )"
+{ $values { "x" "a fixnum" } { "y" "a fixnum" } { "z" "an integer" } }
+{ $description "Primitive version of " { $link * } ". The result may overflow to a bignum." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link * } " instead." } ;
+
+HELP: fixnum/f "( x y -- z )"
+{ $values { "x" "a fixnum" } { "y" "a fixnum" } { "z" "a float" } }
+{ $description "Primitive version of " { $link /f } "." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link /f } " instead." } ;
+
+HELP: fixnum/i "( x y -- z )"
+{ $values { "x" "a fixnum" } { "y" "a fixnum" } { "z" "an integer" } }
+{ $description "Primitive version of " { $link /i } ". The result may overflow to a bignum." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link /i } " instead." } ;
+
+HELP: fixnum-mod "( x y -- z )"
+{ $values { "x" "a fixnum" } { "y" "a fixnum" } { "z" "a fixnum" } }
+{ $description "Primitive version of " { $link mod } ". The result always fits in a fixnum." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link mod } " instead." } ;
+
+HELP: fixnum/mod "( x y -- z w )"
+{ $values { "x" "a fixnum" } { "y" "a fixnum" } { "z" "an integer" } { "w" "a fixnum" } }
+{ $description "Primitive version of " { $link /mod } ". The result may overflow to a bignum." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link /mod } " instead." } ;
+
+HELP: fixnum< "( x y -- ? )"
+{ $values { "x" "a fixnum" } { "y" "a fixnum" } { "?" "a boolean" } }
+{ $description "Primitive version of " { $link < } ". The result may overflow to a bignum." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link < } " instead." } ;
+
+HELP: fixnum<= "( x y -- z )"
+{ $values { "x" "a fixnum" } { "y" "a fixnum" } { "z" "an integer" } }
+{ $description "Primitive version of " { $link <= } ". The result may overflow to a bignum." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link <= } " instead." } ;
+
+HELP: fixnum> "( x y -- ? )"
+{ $values { "x" "a fixnum" } { "y" "a fixnum" } { "?" "a boolean" } }
+{ $description "Primitive version of " { $link > } ". The result may overflow to a bignum." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link > } " instead." } ;
+
+HELP: fixnum>= "( x y -- ? )"
+{ $values { "x" "a fixnum" } { "y" "a fixnum" } { "?" "a boolean" } }
+{ $description "Primitive version of " { $link >= } ". The result may overflow to a bignum." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link >= } " instead." } ;
+
+HELP: fixnum-bitand "( x y -- z )"
+{ $values { "x" "a fixnum" } { "y" "a fixnum" } { "z" "a fixnum" } }
+{ $description "Primitive version of " { $link bitand } ". The result always fits in a fixnum." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitand } " instead." } ;
+
+HELP: fixnum-bitor "( x y -- z )"
+{ $values { "x" "a fixnum" } { "y" "a fixnum" } { "z" "a fixnum" } }
+{ $description "Primitive version of " { $link bitor } ". The result always fits in a fixnum." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitor } " instead." } ;
+
+HELP: fixnum-bitxor "( x y -- z )"
+{ $values { "x" "a fixnum" } { "y" "a fixnum" } { "z" "a fixnum" } }
+{ $description "Primitive version of " { $link bitxor } ". The result always fits in a fixnum." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitxor } " instead." } ;
+
+HELP: fixnum-bitnot "( x -- y )"
+{ $values { "x" "a fixnum" } { "y" "a fixnum" } }
+{ $description "Primitive version of " { $link bitnot } ". The result always fits in a fixnum." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitnot } " instead." } ;
+
+HELP: fixnum-shift "( x y -- z )"
+{ $values { "x" "a fixnum" } { "y" "a fixnum" } { "z" "a fixnum" } }
+{ $description "Primitive version of " { $link shift } ". The result may overflow to a bignum." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link shift } " instead." } ;
+
+HELP: fixnum+fast "( x y -- z )"
+{ $values { "x" "a fixnum" } { "y" "a fixnum" } { "z" "a fixnum" } }
+{ $description "Primitive version of " { $link + } ". Unlike " { $link fixnum+ } ", does not perform an overflow check, so the result may be incorrect." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link + } " instead." } ;
+
+HELP: fixnum-fast "( x y -- z )"
+{ $values { "x" "a fixnum" } { "y" "a fixnum" } { "z" "a fixnum" } }
+{ $description "Primitive version of " { $link - } ". Unlike " { $link fixnum- } ", does not perform an overflow check, so the result may be incorrect." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link - } " instead." } ;
+
 HELP: bignum+ "( x y -- z )"
 { $values { "x" "a bignum" } { "y" "a bignum" } { "z" "a bignum" } }
 { $description "Primitive version of " { $link + } "." }
@@ -74,22 +164,22 @@ HELP: bignum/mod "( x y -- z )"
 { $description "Primitive version of " { $link /mod } "." }
 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link /mod } " instead." } ;
 
-HELP: bignum< "( x y -- z )"
+HELP: bignum< "( x y -- ? )"
 { $values { "x" "a bignum" } { "y" "a bignum" } { "?" "a boolean" } }
 { $description "Primitive version of " { $link < } "." }
 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link < } " instead." } ;
 
-HELP: bignum<= "( x y -- z )"
+HELP: bignum<= "( x y -- ? )"
 { $values { "x" "a bignum" } { "y" "a bignum" } { "?" "a boolean" } }
 { $description "Primitive version of " { $link <= } "." }
 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link <= } " instead." } ;
 
-HELP: bignum> "( x y -- z )"
+HELP: bignum> "( x y -- ? )"
 { $values { "x" "a bignum" } { "y" "a bignum" } { "?" "a boolean" } }
 { $description "Primitive version of " { $link > } "." }
 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link > } " instead." } ;
 
-HELP: bignum>= "( x y -- z )"
+HELP: bignum>= "( x y -- ? )"
 { $values { "x" "a bignum" } { "y" "a bignum" } { "?" "a boolean" } }
 { $description "Primitive version of " { $link >= } "." }
 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link >= } " instead." } ;
@@ -114,6 +204,11 @@ HELP: bignum-bitxor "( x y -- z )"
 { $description "Primitive version of " { $link bitxor } "." }
 { $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitxor } " instead." } ;
 
+HELP: bignum-bitnot "( x -- y )"
+{ $values { "x" "a bignum" } { "y" "a bignum" } }
+{ $description "Primitive version of " { $link bitnot } "." }
+{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitnot } " instead." } ;
+
 HELP: bignum-shift "( x y -- z )"
 { $values { "x" "a bignum" } { "y" "a bignum" } { "z" "a bignum" } }
 { $description "Primitive version of " { $link shift } "." }

library/math/parse-numbers.facts

@@ -1,33 +1,38 @@
-USING: help math prettyprint ;
+USING: help math math-internals prettyprint ;
 
-HELP: base> "( str radix -- n )"
-{ $values { "str" "a string" } { "radix" "an integer between 2 and 36" } { "n" "a real number" } }
-{ $description "Creates a real number from a string representation with the given radix. The radix is ignored for floating point literals; they are always taken to be in base 10." }
-{ $errors "Throws an error if the string cannot be interpreted as a number in the given base." }
+HELP: base> "( str radix -- n/f )"
+{ $values { "str" "a string" } { "radix" "an integer between 2 and 36" } { "n/f" "a real number or " { $link f } } }
+{ $description "Creates a real number from a string representation with the given radix. The radix is ignored for floating point literals; they are always taken to be in base 10."
+$terpri
+"Outputs " { $link f } " if the string does not represent a number." }
 { $see-also >base } ;
 
 HELP: string>number "( str -- n )"
-{ $values { "str" "a string" } { "n" "a real number" } }
-{ $description "Creates a real number from a string representation of a number in base 10." }
-{ $errors "Throws an error if the string cannot be interpreted as a number in base 10." }
+{ $values { "str" "a string" } { "n/f" "a real number or " { $link f } } }
+{ $description "Creates a real number from a string representation of a number in base 10."
+$terpri
+"Outputs " { $link f } " if the string does not represent a number." }
 { $see-also number>string } ;
 
 HELP: bin> "( str -- n )"
-{ $values { "str" "a string" } { "n" "a real number" } }
-{ $description "Creates a real number from a string representation of a number in base 2." }
-{ $errors "Throws an error if the string cannot be interpreted as a number in base 2." }
+{ $values { "str" "a string" } { "n/f" "a real number or " { $link f } } }
+{ $description "Creates a real number from a string representation of a number in base 2."
+$terpri
+"Outputs " { $link f } " if the string does not represent a number." }
 { $see-also POSTPONE: BIN: } ;
 
 HELP: oct> "( str -- n )"
-{ $values { "str" "a string" } { "n" "a real number" } }
-{ $description "Creates a real number from a string representation of a number in base 8." }
-{ $errors "Throws an error if the string cannot be interpreted as a number in base 8." }
+{ $values { "str" "a string" } { "n/f" "a real number or " { $link f } } }
+{ $description "Creates a real number from a string representation of a number in base 8."
+$terpri
+"Outputs " { $link f } " if the string does not represent a number." }
 { $see-also POSTPONE: OCT: } ;
 
 HELP: hex> "( str -- n )"
 { $values { "str" "a string" } { "n" "a real number" } }
-{ $description "Creates a real number from a string representation of a number in base 16." }
-{ $errors "Throws an error if the string cannot be interpreted as a number in base 16." }
+{ $description "Creates a real number from a string representation of a number in base 16."
+$terpri
+"Outputs " { $link f } " if the string does not represent a number." }
 { $see-also POSTPONE: HEX: } ;
 
 HELP: >base "( n radix -- str )"
@@ -53,3 +58,13 @@ HELP: >hex "( n -- str )"
 { $values { "n" "a real number" } { "str" "a string" } }
 { $description "Outputs a string representation of a number using base 16." } 
 { $see-also .h } ;
+
+HELP: string>float "( n -- str )"
+{ $values { "str" "a string" } { "n/f" "a real number or " { $link f } } }
+{ $description "Primitive for creating a float from a string representation. User code should call " { $link string>number } " instead, since it is polymorphic and can handle other types of numbers."
+$terpri
+"Outputs " { $link f } " if the string does not represent a float." } ;
+
+HELP: float>string "( n -- str )"
+{ $values { "n" "a real number" } { "str" "a string" } }
+{ $description "Primitive for getting a string representation of a float. User code should call " { $link number>string } " instead, since it is polymorphic and can handle other types of numbers." } ;

library/test/collections/strings.factor

@@ -93,3 +93,6 @@ unit-test
 [ -6 "hello" nth ] unit-test-fails
 
 [ t ] [ "hello world" dup >vector >string = ] unit-test 
+
+[ "ab" ] [ 2 "abc" resize-string ] unit-test
+[ "abc\0\0\0" ] [ 6 "abc" resize-string ] unit-test

library/tools/memory.facts

@@ -3,7 +3,7 @@ USING: help test ;
 
 HELP: address "( obj -- n )"
 { $values { "obj" "an object" } { "n" "a memory address" } }
-{ $description "Outputs the address where " { $snippet "obj" } " is located in memory. Objects can be moved around by the GC and there is almost never any reason for user code to need to know object addresses." } ;
+{ $description "Outputs the address of an object in memory. Objects can be moved around by the garbage collector and there is almost never any reason for user code to need to know object addresses." } ;
 
 HELP: gc "( n -- )"
 { $values { "n" "a positive integer" } }

library/words.facts

@@ -141,11 +141,12 @@ $low-level-note ;
 
 HELP: (word) "( name vocab -- word )"
 { $values { "name" "a string" } { "vocab" "a string" } { "word" "a word" } }
-{ $description "Low-level word constructor. User code should call " { $link <word> } " instead." } ;
+{ $description "Allocates an uninterned word with the specified name and vocabulary. User code should call " { $link gensym } " to create uninterned words and " { $link create } " to create interned words." }
+{ $see-also <word> } ;
 
 HELP: <word> "( name vocab -- word )"
 { $values { "name" "a string" } { "vocab" "a string" } { "word" "a word" } }
-{ $description "Creates an uninterned word with the specified name and vocabulary. Note that this does not create the vocabulary, nor does it add the word to an existing vocabulary with that name. In most cases, " { $link create } " should be used instead." } ;
+{ $description "Allocates an uninterned word with the specified name and vocabulary, and a blank word properties hashtable. User code should call " { $link gensym } " to create uninterned words and " { $link create } " to create interned words." } ;
 
 HELP: gensym "( -- word )"
 { $values { "word" "a word" } }
@@ -257,3 +258,7 @@ HELP: interned? "( word -- ? )"
 HELP: bootstrap-word "( word -- target )"
 { $values { "word" "a word" } { "target" "a word" } }
 { $description "Looks up a word with the same name and vocabulary as the given word, performing a transformation to handle parsing words in the target dictionary. Used during bootstrap to transfer host words to the target dictionary." } ;
+
+HELP: update-xt "( word -- )"
+{ $values { "word" "a word" } }
+{ $description "Updates a word's execution token based on the value of the " { $link word-primitive } " slot. If the word was compiled, this will lose the compiled definition and make it run in the interpreter." } ;

native/string.c

@@ -83,7 +83,7 @@ void primitive_resize_string(void)
 	CELL capacity = to_fixnum(dpeek2());
 	maybe_gc(string_size(capacity));
 	string = untag_string_fast(dpop());
-	drepl(tag_object(resize_string(string,capacity,F)));
+	drepl(tag_object(resize_string(string,capacity,0)));
 }
 
 /* Some ugly macros to prevent a 2x code duplication */