steve
/
factor
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

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

db4
Slava Pestov 2009-07-24 20:29:09 -05:00
parent 4fcd05cef7 990b1e1249
commit 93764faad3
8 changed files with 90 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
basis/tools/scaffold/scaffold.factor
View File

@ -124,7 +124,7 @@ M: bad-developer-name summary
{ "str" string }
{ "hash" hashtable }
{ "hashtable" hashtable }
{ "?" "a boolean" }
{ "?" boolean }
{ "ch" "a character" }
{ "word" word }
{ "array" array }

54
core/math/floats/floats-docs.factor
View File

@ -1,26 +1,6 @@
USING: help.markup help.syntax math math.private ;
IN: math.floats
ARTICLE: "floats" "Floats"
{ $subsection float }
"Rational numbers represent " { $emphasis "exact" } " quantities. On the other hand, a floating point number is an " { $emphasis "approximation" } ". While rationals can grow to any required precision, floating point numbers are fixed-width, and manipulating them is usually faster than manipulating ratios or bignums (but slower than manipulating fixnums). Floating point numbers are often used to represent irrational numbers, which have no exact representation as a ratio of two integers."
$nl
"Introducing a floating point number in a computation forces the result to be expressed in floating point."
{ $example "5/4 1/2 + ." "1+3/4" }
{ $example "5/4 0.5 + ." "1.75" }
"Integers and rationals can be converted to floats:"
{ $subsection >float }
"Two real numbers can be divided yielding a float result:"
{ $subsection /f }
"Floating point numbers are represented internally in IEEE 754 double-precision format. This internal representation can be accessed for advanced operations and input/output purposes."
{ $subsection float>bits }
{ $subsection double>bits }
{ $subsection bits>float }
{ $subsection bits>double }
{ $see-also "syntax-floats" } ;
ABOUT: "floats"
HELP: float
{ $class-description "The class of double-precision floating point numbers." } ;
@ -91,3 +71,37 @@ HELP: float>= ( x y -- ? )
{ $values { "x" float } { "y" 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." } ;
ARTICLE: "floats" "Floats"
{ $subsection float }
"Rational numbers represent " { $emphasis "exact" } " quantities. On the other hand, a floating point number is an " { $emphasis "approximation" } ". While rationals can grow to any required precision, floating point numbers are fixed-width, and manipulating them is usually faster than manipulating ratios or bignums (but slower than manipulating fixnums). Floating point numbers are often used to represent irrational numbers, which have no exact representation as a ratio of two integers."
$nl
"Introducing a floating point number in a computation forces the result to be expressed in floating point."
{ $example "5/4 1/2 + ." "1+3/4" }
{ $example "5/4 0.5 + ." "1.75" }
"Integers and rationals can be converted to floats:"
{ $subsection >float }
"Two real numbers can be divided yielding a float result:"
{ $subsection /f }
"Floating point numbers are represented internally in IEEE 754 double-precision format. This internal representation can be accessed for advanced operations and input/output purposes."
{ $subsection float>bits }
{ $subsection double>bits }
{ $subsection bits>float }
{ $subsection bits>double }
"Constructing floating point NaNs:"
{ $subsection <fp-nan> }
"Floating point numbers are discrete:"
{ $subsection prev-float }
{ $subsection next-float }
"Introspection on floating point numbers:"
{ $subsection fp-special? }
{ $subsection fp-nan? }
{ $subsection fp-qnan? }
{ $subsection fp-snan? }
{ $subsection fp-infinity? }
{ $subsection fp-nan-payload }
"Comparing two floating point numbers:"
{ $subsection fp-bitwise= }
{ $see-also "syntax-floats" } ;
ABOUT: "floats"

15
core/math/math-docs.factor
View File

@ -12,19 +12,19 @@ HELP: number=
} ;
HELP: <
{ $values { "x" real } { "y" real } { "?" "a boolean" } }
{ $values { "x" real } { "y" real } { "?" boolean } }
{ $description "Tests if " { $snippet "x" } " is less than " { $snippet "y" } "." } ;
HELP: <=
{ $values { "x" real } { "y" real } { "?" "a boolean" } }
{ $values { "x" real } { "y" real } { "?" boolean } }
{ $description "Tests if " { $snippet "x" } " is less than or equal to " { $snippet "y" } "." } ;
HELP: >
{ $values { "x" real } { "y" real } { "?" "a boolean" } }
{ $values { "x" real } { "y" real } { "?" boolean } }
{ $description "Tests if " { $snippet "x" } " is greater than " { $snippet "y" } "." } ;
HELP: >=
{ $values { "x" real } { "y" real } { "?" "a boolean" } }
{ $values { "x" real } { "y" real } { "?" boolean } }
{ $description "Tests if " { $snippet "x" } " is greater than or equal to " { $snippet "y" } "." } ;
@ -245,6 +245,13 @@ HELP: times
{ $example "USING: io math ;" "3 [ \"Hi\" print ] times" "Hi\nHi\nHi" }
} ;
HELP: fp-bitwise=
{ $values
{ "x" float } { "y" float }
{ "?" boolean }
}
{ $description "Compares two floating point numbers for bit equality." } ;
HELP: fp-special?
{ $values { "x" real } { "?" "a boolean" } }
{ $description "Tests if " { $snippet "x" } " is an IEEE special value (Not-a-Number or Infinity). While " { $snippet "x" } " can be any real number, this word will only ever yield true if " { $snippet "x" } " is a " { $link float } "." } ;

40
core/sequences/sequences-docs.factor
View File

@ -627,7 +627,7 @@ HELP: slice-error
} ;
HELP: slice
{ $class-description "A virtual sequence which presents a subrange of the elements of an underlying sequence. New instances can be created by calling " { $link <slice> } "."
{ $class-description "A virtual sequence which presents a subrange of the elements of an underlying sequence. New instances can be created by calling " { $link <slice> } ". Convenience words are also provided for creating slices where one endpoint is the start or end of the sequence; see " { $link "sequences-slices" } " for a list."
$nl
"Slices are mutable if the underlying sequence is mutable, and mutating a slice changes the underlying sequence. However, slices cannot be resized after creation." } ;
@ -1311,6 +1311,20 @@ HELP: iota
}
} ;
HELP: assert-sequence=
{ $values
{ "a" sequence } { "b" sequence }
}
{ $description "Throws an error if all the elements of two sequences, taken pairwise, are not equal." }
{ $notes "The sequences need not be of the same type." }
{ $examples
{ $example
"USING: prettyprint sequences ;"
"{ 1 2 3 } V{ 1 2 3 } assert-sequence="
""
}
} ;
ARTICLE: "sequences-unsafe" "Unsafe sequence operations"
"The " { $link nth-unsafe } " and " { $link set-nth-unsafe } " sequence protocol bypasses bounds checks for increased performance."
$nl
@ -1357,7 +1371,15 @@ ARTICLE: "virtual-sequences-protocol" "Virtual sequence protocol"
{ $subsection virtual@ } ;
ARTICLE: "virtual-sequences" "Virtual sequences"
"Virtual sequences allow different ways of accessing a sequence without having to create a new sequence or a new data structure altogether. To do this, they translate the virtual index into a normal index into an underlying sequence using the " { $link "virtual-sequences-protocol" } "."
"A virtual sequence is an implementation of the " { $link "sequence-protocol" } " which does not store its own elements, and instead computes them, either from scratch or by retrieving them from another sequence."
$nl
"Implementations include the following:"
{ $list
{ $link reversed }
{ $link slice }
{ $link iota }
}
"Virtual sequences can be implemented with the " { $link "virtual-sequences-protocol" } ", by translating an index in the virtual sequence into an index in another sequence:"
{ $subsection "virtual-sequences-protocol" } ;
ARTICLE: "sequences-integers" "Counted loops"
@ -1422,6 +1444,16 @@ ARTICLE: "sequences-appending" "Appending sequences"
{ $subsection pad-tail } ;
ARTICLE: "sequences-slices" "Subsequences and slices"
"There are two ways to extract a subrange of elements from a sequence. The first approach creates a new sequence of the same type as the input, which does not share storage with the underlying sequence. This takes time proportional to the number of elements being extracted. The second approach creates a " { $emphasis "slice" } ", which is a virtual sequence (see " { $link "virtual-sequences" } ") sharing storage with the original sequence. Slices are constructed in constant time."
$nl
"Some general guidelines for choosing between the two approaches:"
{ $list
"If you are using mutable state, the choice has to be made one way or another because of semantics; mutating a slice will change the underlying sequence."
{ "Using a slice can improve algorithmic complexity. For example, if each iteration of a loop decomposes a sequence using " { $link first } " and " { $link rest } ", then the loop will run in quadratic time, relative to the length of the sequence. Using " { $link rest-slice } " changes the loop to run in linear time, since " { $link rest-slice } " does not copy any elements. Taking a slice of a slice will “collapse” the slice so to avoid the double indirection, so it is safe to use slices in recursive code." }
"Accessing elements from a concrete sequence (such as a string or an array) is often faster than accessing elements from a slice, because slice access entails additional indirection. However, in some cases, if the slice is immediately consumed by an iteration combinator, the compiler can eliminate the slice allocation and indirect altogether."
"If the slice outlives the original sequence, the original sequence will still remain in memory, since the slice will reference it. This can increase memory consumption unnecessarily."
}
{ $heading "Subsequence operations" }
"Extracting a subsequence:"
{ $subsection subseq }
{ $subsection head }
@ -1436,7 +1468,8 @@ ARTICLE: "sequences-slices" "Subsequences and slices"
{ $subsection unclip-last }
{ $subsection cut }
{ $subsection cut* }
"A " { $emphasis "slice" } " is a virtual sequence which presents as view of a subsequence of an underlying sequence:"
{ $heading "Slice operations" }
"The slice data type:"
{ $subsection slice }
{ $subsection slice? }
"Extracting a slice:"
@ -1591,6 +1624,7 @@ ARTICLE: "sequences-comparing" "Comparing sequences"
{ $subsection sequence= }
{ $subsection mismatch }
{ $subsection drop-prefix }
{ $subsection assert-sequence= }
"The " { $link <=> } " generic word performs lexicographic comparison when applied to sequences." ;
ARTICLE: "sequences-f" "The f object as a sequence"

2
extra/alien/inline/inline.factor
View File

@ -65,7 +65,7 @@ PRIVATE>
concat make-function ;
: define-c-library ( name -- )
c-library-name c-library set
c-library-name [ c-library set ] [ "c-library" set ] bi
V{ } clone c-strings set
V{ } clone linker-args set ;

6
extra/alien/inline/syntax/syntax-docs.factor
View File

@ -95,6 +95,6 @@ HELP: DELETE-C-LIBRARY:
}
{ $see-also POSTPONE: delete-inline-library } ;
HELP: RAW-C:
{ $syntax "RAW-C:" "body" ";" }
{ $description "Insert a string into the generated source file. Useful for macros and other details not implemented in " { $snippet "alien.inline" } "." } ;
HELP: <RAW-C
{ $syntax "<RAW-C code RAW-C>" }
{ $description "Insert a (multiline) string into the generated source file. Useful for macros and other details not implemented in " { $snippet "alien.inline" } "." } ;

2
extra/alien/inline/syntax/syntax.factor
View File

@ -28,4 +28,4 @@ SYNTAX: ;C-LIBRARY compile-c-library ;
SYNTAX: DELETE-C-LIBRARY: scan delete-inline-library ;
SYNTAX: RAW-C: parse-here raw-c ;
SYNTAX: <RAW-C "RAW-C>" parse-multiline-string raw-c ;

4
extra/alien/marshall/marshall-docs.factor
View File

@ -330,7 +330,7 @@ HELP: out-arg-unmarshaller
HELP: class-unmarshaller
{ $values
{ "type" " a C type string" }
{ "quot" quotation }
{ "quot/f" quotation }
}
{ $description "If in the vocab in which this word is called, there is a subclass of " { $link alien-wrapper }
" named after the type argument, " { $snippet "pointer-unmarshaller" } " will return a quotation which "
@ -376,7 +376,7 @@ HELP: struct-primitive-unmarshaller
HELP: struct-unmarshaller
{ $values
{ "type" "a C type string" }
{ "quot" quotation }
{ "quot/f" quotation }
}
{ $description "Returns a quotation which wraps its argument in the subclass of "
{ $link struct-wrapper } " which matches the " { $snippet "type" } " arg."