{ $description "Outputs the a vector containing a copy of the data stack contents right before the call to this word, with the top of the stack at the end of the vector." } ;
{ $description "Replaces the data stack contents with a copy of a vector. The end of the vector becomes the top of the stack." } ;
HELP: retainstack "( -- rs )"
{ $values { "rs" "a vector" } }
{ $description "Outputs the a vector containing a copy of the retain stack contents right before the call to this word, with the top of the stack at the end of the vector." } ;
HELP: set-retainstack "( rs -- )"
{ $values { "rs" "a vector" } }
{ $description "Replaces the retain stack contents with a copy of a vector. The end of the vector becomes the top of the stack." } ;
{ $description "Outputs the a vector containing a copy of the call stack contents right before the call to this word, with the top of the stack at the end of the vector. The call frame of the caller word is " { $emphasis "not" } " included." } ;
{ $description "Replaces the call stack contents with a copy of a vector. The end of the vector becomes the top of the stack. The current quotation continues executing. The new callstack takes effect when the current quotation returns, resulting in a callframe being popped." } ;
{ "if two objects are equal under " { $link = } ", they must have equal hashcodes" }
"the hashcode is only permitted to change if the object is mutated in some way"
}
"If mutable objects are used as hashtable keys, they must not be mutated in such a way that their hashcode changes. Doing so will violate bucket sorting invariants and result in undefined behavior." } ;
{ "two numbers are equal if they have the same numerical value after being upgraded to the highest type of the two (see " { $link "number-protocol" } ")" }
"two sequences are equal if they have the same type and elements"
"two tuples are equal if their classes and slot values are equal"
"The default implementation treats the two objects as sequences, and recursively compares their elements. So no extra work is required to compare sequences lexicographically."
{ $contract "Outputs a new object equal to the given object. This is not guaranteed to actually copy the object; it does nothing with immutable objects, and does not copy words either. However, sequences and tuples can be cloned to obtain a shallow copy of the original." } ;
{ $description "Sets the initial quotation called by the runtime as the last stage of startup. The image must be saved for changes to the boot quotation to take effect. Usually the boot quotation should not be changed." } ;
HELP: num-types "( -- n )"
{ $values { "n" "a postiive integer" } }
{ $description "Outputs one more than the maximum value from the " { $link type } " primitive." } ;
{ $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." }
{ $description "Chooses between two values depending on the boolean value of " { $snippet "cond" } "." } ;
HELP: >boolean "( obj -- ? )"
{ $values { "obj" "a generalized boolean" } { "?" "a boolean" } }
{ $description "Convert a generalized boolean into a boolean. That is, " { $link f } " retains its value, whereas anything else becomes " { $link t } "." } ;
HELP: not "( obj -- ? )"
{ $values { "obj" "a generalized boolean" } { "?" "a boolean" } }
{ $description "For " { $link f } " outputs " { $link t } " and for anything else outputs " { $link f } "." } ;
HELP: and "( obj1 obj2 -- ? )"
{ $values { "obj1" "a generalized boolean" } { "obj2" "a generalized boolean" } { "obj" "a generalized boolean" } }
{ $description "Tests if neither object is " { $link f } "." } ;
HELP: or "( obj1 obj2 -- ? )"
{ $values { "obj1" "a generalized boolean" } { "obj2" "a generalized boolean" } { "obj" "a generalized boolean" } }
{ $description "Tests if at least one object is not " { $link f } "." } ;
HELP: cpu "( -- cpu )"
{ $values { "cpu" "a string" } }
{ $description
"Outputs a string descriptor of the current CPU architecture. Currently, this set of descriptors is:"
{ $code "amd64" "ppc" "x86" }
} ;
HELP: os "( -- os )"
{ $values { "os" "a string" } }
{ $description
"Outputs a string descriptor of the current operating system family. Currently, this set of descriptors is:"
{ $description "Push the current callframe on the callstack, and set the callframe to the given quotation. Conceptually, calls the quotation, as if its definition was substituted at the location of the call." }
{ $values { "cond" "a generalized boolean" } { "false" "a quotation" } }
{ $description "If " { $snippet "cond" } " is " { $link f } ", calls the " { $snippet "false" } " quotation."
$terpri
"The " { $snippet "cond" } " value is removed from the stack before the quotation is called." } ;
HELP: if* "( cond true false -- )"
{ $values { "cond" "a generalized boolean" } { "true" "a quotation with stack effect " { $snippet "( cond -- )" } } { "false" "a quotation" } }
{ $description "Alternative conditional form that preserves the " { $snippet "cond" } " value if it is true."
$terpri
"If the condition is true, it is retained on the stack before the " { $snippet "true" } " quotation is called. Otherwise, the condition is removed from the stack and the " { $snippet "false" } " quotation is called."
$terpri
"The following two lines are equivalent:"
{ $code "X [ Y ] [ Z ] if*" "X dup [ Y ] [ drop Z ] if" } } ;
{ $description "If the condition is " { $link f } ", the " { $snippet "false" } " quotation is called with the " { $snippet "default" } " value on the stack. Otherwise, the " { $snippet "true" } " quotation is called with the condition on the stack."
"However, if we declare that the top of the stack is a " { $link float } ", then type checks and generic dispatch are eliminated, and the compiler can use unsafe intrinsics:"
{ $warning "This word is in the " { $snippet "kernel-internals" } " vocabulary because it is unsafe. It does not check types, so improper use can corrupt memory." } ;
{ $warning "This word is in the " { $snippet "kernel-internals" } " vocabulary because it is unsafe. It does not check types or array bounds, and improper use can corrupt memory." } ;
{ $warning "This word is in the " { $snippet "kernel-internals" } " vocabulary because it is unsafe. It does not check types or array bounds, and improper use can corrupt memory." } ;
{ $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" } }
{ $description "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." } ;
{ $description "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." } ;
{ $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." } ;
{ $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." } ;
{ $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." } ;
