-USING: arrays byte-arrays help.markup help.syntax kernel\r
-byte-vectors.private combinators ;\r
+USING: arrays byte-arrays help.markup help.syntax kernel combinators ;\r
IN: byte-vectors\r
\r
ARTICLE: "byte-vectors" "Byte vectors"\r
-"A byte vector is a resizable mutable sequence of unsigned bytes. Byte vector words are found in the " { $vocab-link "byte-vectors" } " vocabulary."\r
+"The " { $vocab-link "byte-vectors" } " vocabulary implements resizable mutable sequence of unsigned bytes. Byte vectors implement the " { $link "sequence-protocol" } " and thus all " { $link "sequences" } " can be used with them."\r
$nl\r
"Byte vectors form a class:"\r
{ $subsection byte-vector }\r
USING: help.markup help.syntax
-kernel kernel.private prettyprint sequences.private ;
+kernel kernel.private prettyprint sequences.private sequences ;
IN: arrays
+ARTICLE: "arrays-unsafe" "Unsafe array operations"
+"These two words are used internally by the Factor implementation. User code should never need to call them; instead use " { $link nth } " and " { $link set-nth } "."
+{ $subsection array-nth }
+{ $subsection set-array-nth } ;
+
ARTICLE: "arrays" "Arrays"
-"Arrays are fixed-size mutable sequences (" { $link "sequence-protocol" } "). The literal syntax is covered in " { $link "syntax-arrays" } ". Resizable arrays also exist and are called vectors; see " { $link "vectors" } "."
+"The " { $vocab-link "arrays" } " vocabulary implements fixed-size mutable sequences which support the " { $link "sequence-protocol" } "."
+$nl
+"The " { $vocab-link "arrays" } " vocabulary only includes words for creating new arrays. To access and modify array elements, use " { $link "sequences" } " in the " { $vocab-link "sequences" } " vocabulary."
$nl
-"Array words are in the " { $vocab-link "arrays" } " vocabulary. Unsafe implementation words are in the " { $vocab-link "sequences.private" } " vocabulary."
+"Array literal syntax is documented in " { $link "syntax-arrays" } ". Resizable arrays also exist and are known as " { $link "vectors" } "."
$nl
"Arrays form a class of objects:"
{ $subsection array }
{ $subsection 2array }
{ $subsection 3array }
{ $subsection 4array }
-"Arrays can be accessed without bounds checks in a pointer unsafe way."
-{ $subsection array-nth }
-{ $subsection set-array-nth }
"The class of two-element arrays:"
-{ $subsection pair } ;
+{ $subsection pair }
+"Arrays can be accessed without bounds checks in a pointer unsafe way."
+{ $subsection "arrays-unsafe" } ;
ABOUT: "arrays"
ARTICLE: "hashtables" "Hashtables"
"A hashtable provides efficient (expected constant time) lookup and storage of key/value pairs. Keys are compared for equality, and a hashing function is used to reduce the number of comparisons made. The literal syntax is covered in " { $link "syntax-hashtables" } "."
$nl
-"Hashtable words are in the " { $vocab-link "hashtables" } " vocabulary. Unsafe implementation words are in the " { $vocab-link "hashtables.private" } " vocabulary."
-$nl
-"Hashtables implement the " { $link "assocs-protocol" } "."
+"Words for constructing hashtables are in the " { $vocab-link "hashtables" } " vocabulary. Hashtables implement the " { $link "assocs-protocol" } ", and all " { $link "assocs" } " can be used on them; there are no hashtable-specific words to access and modify keys, because associative mapping operations are generic and work with all associative mappings."
$nl
"Hashtables are a class of objects."
{ $subsection hashtable }
IN: sbufs
ARTICLE: "sbufs" "String buffers"
-"A string buffer is a resizable mutable sequence of characters. The literal syntax is covered in " { $link "syntax-sbufs" } "."
+"The " { $vocab-link "sbufs" } " vocabulary implements resizable mutable sequence of characters. The literal syntax is covered in " { $link "syntax-sbufs" } "."
$nl
-"String buffers can be used to construct new strings by accumilating substrings and characters, however usually they are only used indirectly, since the sequence construction words are more convenient to use in most cases (see " { $link "namespaces-make" } ")."
-$nl
-"String buffer words are found in the " { $vocab-link "sbufs" } " vocabulary."
+"String buffers implement the " { $link "sequence-protocol" } " and thus all " { $link "sequences" } " can be used with them. String buffers can be used to construct new strings by accumilating substrings and characters, however usually they are only used indirectly, since the sequence construction words are more convenient to use in most cases (see " { $link "namespaces-make" } ")."
$nl
"String buffers form a class of objects:"
{ $subsection sbuf }
HELP: array-nth
{ $values { "n" "a non-negative fixnum" } { "array" "an array" } { "elt" object } }
{ $description "Low-level array element accessor." }
-{ $warning "This word is in the " { $vocab-link "sequences.private" } " 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 " { $vocab-link "sequences.private" } " vocabulary because it is unsafe. It does not check types or array bounds, and improper use can corrupt memory. User code must use " { $link nth } " instead." } ;
HELP: set-array-nth
{ $values { "elt" object } { "n" "a non-negative fixnum" } { "array" "an array" } }
{ $description "Low-level array element mutator." }
-{ $warning "This word is in the " { $vocab-link "sequences.private" } " 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 " { $vocab-link "sequences.private" } " vocabulary because it is unsafe. It does not check types or array bounds, and improper use can corrupt memory. User code must use " { $link set-nth } " instead." } ;
HELP: collect
{ $values { "n" "a non-negative integer" } { "quot" { $quotation "( n -- value )" } } { "into" "a sequence of length at least " { $snippet "n" } } }
USING: arrays byte-arrays help.markup help.syntax
kernel kernel.private strings.private sequences vectors
-sbufs math ;
+sbufs math tools.vocabs.browser ;
IN: strings
ARTICLE: "strings" "Strings"
-"A string is a fixed-size mutable sequence of Unicode 5.1 code points."
+"The " { $vocab-link "strings" } " vocabulary implements fixed-size mutable sequences of of Unicode 5.1 code points."
$nl
-"Characters are not a first-class type; they are simply represented as integers between 0 and 16777216 (2^24). Only characters up to 2097152 (2^21) have a defined meaning in Unicode."
+"Code points, or characters as they're informally known, are not a first-class type; they are simply represented as integers in the range 0 and 16,777,216 (2^24), inclusive. Only characters up to 2,097,152 (2^21) have a defined meaning in Unicode."
$nl
"String literal syntax is covered in " { $link "syntax-strings" } "."
$nl
-"String words are found in the " { $vocab-link "strings" } " vocabulary."
+"Since strings implement the " { $link "sequence-protocol" } ", basic string manipulation can be performed with " { $link "sequences" } " in the " { $vocab-link "sequences" } " vocabulary. More text processing functionality can be found in vocabularies carrying the " { $link T{ vocab-tag { name "text" } } } " tag."
$nl
"Strings form a class:"
{ $subsection string }
{ $subsection string? }
-"Creating strings:"
+"Creating new strings:"
{ $subsection >string }
{ $subsection <string> }
"Creating a string from a single character:"
-{ $subsection 1string }
-"Since strings are sequences, basic string manipulation can be performed using sequence operations (" { $link "sequences" } "). More advanced functionality can be found in other vocabularies, including but not limited to:"
-{ $list
- { { $link "ascii" } " - ASCII algorithms for interoperability with legacy applications" }
- { { $link "unicode" } " - Unicode algorithms for modern multilingual applications" }
- { { $vocab-link "regexp" } " - regular expressions" }
- { { $vocab-link "peg" } " - parser expression grammars" }
-} ;
+{ $subsection 1string } ;
ABOUT: "strings"
IN: vectors
ARTICLE: "vectors" "Vectors"
-"A vector is a resizable mutable sequence of objects. The literal syntax is covered in " { $link "syntax-vectors" } ". Vector words are found in the " { $vocab-link "vectors" } " vocabulary."
+"The " { $vocab-link "vectors" } " vocabulary implements resizable mutable sequence which support the " { $link "sequence-protocol" } "."
$nl
-"Vectors form a class:"
+"The " { $vocab-link "vectors" } " vocabulary only includes words for creating new vectors. To access and modify vector elements, use " { $link "sequences" } " in the " { $vocab-link "sequences" } " vocabulary."
+$nl
+"Vector literal syntax is documented in " { $link "syntax-vectors" } "."
+$nl
+"Vectors are intended to be used with " { $link "sequences-destructive" } ". Code that does not modify sequences in-place can use fixed-size arrays without loss of generality; see " { $link "arrays" } "."
+$nl
+"Vectors form a class of objects:"
{ $subsection vector }
{ $subsection vector? }
-"Creating vectors:"
+"Creating new vectors:"
{ $subsection >vector }
{ $subsection <vector> }
"Creating a vector from a single element:"
{ $subsection 1vector }
-"If you don't care about initial capacity, a more elegant way to create a new vector is to write:"
+"If you don't care about initial capacity, an elegant way to create a new vector is to write:"
{ $code "V{ } clone" } ;
ABOUT: "vectors"
projects / factor.git / commitdiff