IN: math.functions
ARTICLE: "integer-functions" "Integer functions"
- { $subsection align }
- { $subsection gcd }
- { $subsection log2 }
- { $subsection next-power-of-2 }
+ { $subsections
+ align
+ gcd
+ log2
+ next-power-of-2
+ }
"Modular exponentiation:"
- { $subsection ^mod }
- { $subsection mod-inv }
+ { $subsections ^mod mod-inv }
"Tests:"
- { $subsection power-of-2? }
- { $subsection even? }
- { $subsection odd? }
- { $subsection divisor? } ;
+ { $subsections
+ power-of-2?
+ even?
+ odd?
+ divisor?
+ } ;
ARTICLE: "arithmetic-functions" "Arithmetic functions"
"Computing additive and multiplicative inverses:"
- { $subsection neg }
- { $subsection recip }
+ { $subsections neg recip }
"Complex conjugation:"
- { $subsection conjugate }
+ { $subsections conjugate }
"Tests:"
- { $subsection zero? }
- { $subsection between? }
+ { $subsections zero? between? }
"Control flow:"
- { $subsection if-zero }
- { $subsection when-zero }
- { $subsection unless-zero }
+ { $subsections
+ if-zero
+ when-zero
+ unless-zero
+ }
"Sign:"
- { $subsection sgn }
+ { $subsections sgn }
"Rounding:"
- { $subsection ceiling }
- { $subsection floor }
- { $subsection truncate }
- { $subsection round }
+ { $subsections
+ ceiling
+ floor
+ truncate
+ round
+ }
"Inexact comparison:"
- { $subsection ~ }
+ { $subsections ~ }
"Numbers implement the " { $link "math.order" } ", therefore operations such as " { $link min } " and " { $link max } " can be used with numbers." ;
ARTICLE: "power-functions" "Powers and logarithms"
"Squares:"
- { $subsection sq }
- { $subsection sqrt }
+ { $subsections sq sqrt }
"Exponential and natural logarithm:"
- { $subsection exp }
- { $subsection cis }
- { $subsection log }
-{ $subsections
- exp
- cis
- log
- log1+
- log10
-}
++{ $subsections exp cis log }
+"Other logarithms:"
- { $subsection log1+ }
- { $subsection log10 }
++{ $subsection log1+ log10 }
"Raising a number to a power:"
- { $subsection ^ }
- { $subsection 10^ }
+ { $subsections ^ 10^ }
"Converting between rectangular and polar form:"
- { $subsection abs }
- { $subsection absq }
- { $subsection arg }
- { $subsection >polar }
- { $subsection polar> } ;
+ { $subsections
+ abs
+ absq
+ arg
+ >polar
+ polar>
+ } ;
ARTICLE: "trig-hyp-functions" "Trigonometric and hyperbolic functions"
"Trigonometric functions:"
- { $subsection cos }
- { $subsection sin }
- { $subsection tan }
+ { $subsections cos sin tan }
"Reciprocals:"
- { $subsection sec }
- { $subsection cosec }
- { $subsection cot }
+ { $subsections sec cosec cot }
"Inverses:"
- { $subsection acos }
- { $subsection asin }
- { $subsection atan }
+ { $subsections acos asin atan }
"Inverse reciprocals:"
- { $subsection asec }
- { $subsection acosec }
- { $subsection acot }
+ { $subsections asec acosec acot }
"Hyperbolic functions:"
- { $subsection cosh }
- { $subsection sinh }
- { $subsection tanh }
+ { $subsections cosh sinh tanh }
"Reciprocals:"
- { $subsection sech }
- { $subsection cosech }
- { $subsection coth }
+ { $subsections sech cosech coth }
"Inverses:"
- { $subsection acosh }
- { $subsection asinh }
- { $subsection atanh }
+ { $subsections acosh asinh atanh }
"Inverse reciprocals:"
- { $subsection asech }
- { $subsection acosech }
- { $subsection acoth } ;
+ { $subsections asech acosech acoth } ;
ARTICLE: "math-functions" "Mathematical functions"
- { $subsection "integer-functions" }
- { $subsection "arithmetic-functions" }
- { $subsection "power-functions" }
- { $subsection "trig-hyp-functions" } ;
+ { $subsections
+ "integer-functions"
+ "arithmetic-functions"
+ "power-functions"
+ "trig-hyp-functions"
+ } ;
ABOUT: "math-functions"
! Copyright (C) 2008, 2009 Doug Coleman, Daniel Ehrenberg.
! See http://factorcode.org/license.txt for BSD license.
USING: kernel strings help.markup help.syntax math regexp.parser
-regexp.ast multiline ;
+regexp.ast ;
IN: regexp
ABOUT: "regexp"
ARTICLE: "regexp" "Regular expressions"
"The " { $vocab-link "regexp" } " vocabulary provides word for creating and using regular expressions."
- { $subsection { "regexp" "intro" } }
+ { $subsections { "regexp" "intro" } }
"The class of regular expressions:"
- { $subsection regexp }
+ { $subsections regexp }
"Basic usage:"
- { $subsection { "regexp" "syntax" } }
- { $subsection { "regexp" "options" } }
- { $subsection { "regexp" "construction" } }
- { $subsection { "regexp" "operations" } }
+ { $subsections
+ { "regexp" "syntax" }
+ { "regexp" "options" }
+ { "regexp" "construction" }
+ { "regexp" "operations" }
+ }
"Advanced topics:"
{ $vocab-subsection "Regular expression combinators" "regexp.combinators" }
- { $subsection { "regexp" "theory" } }
- { $subsection { "regexp" "deploy" } } ;
+ { $subsections
+ { "regexp" "theory" }
+ { "regexp" "deploy" }
+ } ;
ARTICLE: { "regexp" "intro" } "A quick introduction to regular expressions"
"Regular expressions are a terse way to do certain simple string processing tasks. For example, to replace all instances of " { $snippet "foo" } " in one string with " { $snippet "bar" } ", the following can be used:"
"The " { $snippet "+" } " operator matches one or more occurrences of the previous expression; in this case " { $snippet "o" } ". Another useful feature is alternation. Say we want to do this replacement with fooooo or boooo. Then we could use the code"
{ $code "R/ (f|b)oo+/ \"bar\" re-replace" }
"To search a file for all lines that match a given regular expression, you could use code like this:"
-{ $code <" "file.txt" ascii file-lines [ R/ (f|b)oo+/ re-contains? ] filter "> }
+{ $code """"file.txt" ascii file-lines [ R/ (f|b)oo+/ re-contains? ] filter""" }
"To test if a string in its entirety matches a regular expression, the following can be used:"
-{ $example <" USE: regexp "fooo" R/ (b|f)oo+/ matches? . "> "t" }
+{ $example """USE: regexp "fooo" R/ (b|f)oo+/ matches? .""" "t" }
"Regular expressions can't be used for all parsing tasks. For example, they are not powerful enough to match balancing parentheses." ;
ARTICLE: { "regexp" "construction" } "Constructing regular expressions"
"Most of the time, regular expressions are literals and the parsing word should be used, to construct them at parse time. This ensures that they are only compiled once, and gives parse time syntax checking."
- { $subsection POSTPONE: R/ }
+ { $subsections POSTPONE: R/ }
"Sometimes, regular expressions need to be constructed at run time instead; for example, in a text editor, the user might input a regular expression to search for in a document."
- { $subsection <regexp> }
- { $subsection <optioned-regexp> }
+ { $subsections <regexp> <optioned-regexp> }
"Another approach is to use " { $vocab-link "regexp.combinators" } "." ;
ARTICLE: { "regexp" "syntax" } "Regular expression syntax"
ARTICLE: { "regexp" "operations" } "Matching operations with regular expressions"
"Testing if a string matches a regular expression:"
- { $subsection matches? }
+ { $subsections matches? }
"Finding a match inside a string:"
- { $subsection re-contains? }
- { $subsection first-match }
+ { $subsections re-contains? first-match }
"Finding all matches inside a string:"
- { $subsection count-matches }
- { $subsection all-matching-slices }
- { $subsection all-matching-subseqs }
+ { $subsections
+ count-matches
+ all-matching-slices
+ all-matching-subseqs
+ }
"Splitting a string into tokens delimited by a regular expression:"
- { $subsection re-split }
+ { $subsections re-split }
"Replacing occurrences of a regular expression with a string:"
- { $subsection re-replace } ;
+ { $subsections re-replace } ;
ARTICLE: { "regexp" "deploy" } "Regular expressions and the deploy tool"
"The " { $link "tools.deploy" } " tool has the option to strip out the optimizing compiler from the resulting image. Since regular expressions compile to Factor code, this creates a minor performance-related caveat."
"The cleave combinators apply multiple quotations to a single value."
$nl
"Two quotations:"
- { $subsection bi }
- { $subsection 2bi }
- { $subsection 3bi }
+ { $subsections bi 2bi 3bi }
"Three quotations:"
- { $subsection tri }
- { $subsection 2tri }
- { $subsection 3tri }
+ { $subsections tri 2tri 3tri }
"An array of quotations:"
- { $subsection cleave }
- { $subsection 2cleave }
- { $subsection 3cleave }
+ { $subsection cleave 2cleave 3cleave }
+ $nl
"Technically, the cleave combinators are redundant because they can be simulated using shuffle words and other combinators, and in addition, they do not reduce token counts by much, if at all. However, they can make code more readable by expressing intention and exploiting any inherent symmetry. For example, a piece of code which performs three operations on the top of the stack can be written in one of two ways:"
{ $code
"! First alternative; uses keep"
"[ 2 * ] tri"
}
"The latter is more aesthetically pleasing than the former."
+ $nl
{ $subsection "cleave-shuffle-equivalence" } ;
ARTICLE: "spread-shuffle-equivalence" "Expressing shuffle words with spread combinators"
} ;
ARTICLE: "spread-combinators" "Spread combinators"
-"The spread combinators apply multiple quotations to multiple values. The " { $snippet "*" } " suffix signifies spreading."
+"The spread combinators apply multiple quotations to multiple values. In this case, " { $snippet "*" } " suffix signify spreading."
$nl
"Two quotations:"
- { $subsection bi* }
- { $subsection 2bi* }
+ { $subsections bi* 2bi* }
"Three quotations:"
- { $subsection tri* }
- { $subsection 2tri* }
+ { $subsections tri* 2tri* }
"An array of quotations:"
- { $subsection spread }
+ { $subsections spread }
"Technically, the spread combinators are redundant because they can be simulated using shuffle words and other combinators, and in addition, they do not reduce token counts by much, if at all. However, they can make code more readable by expressing intention and exploiting any inherent symmetry. For example, a piece of code which performs three operations on three related values can be written in one of two ways:"
{ $code
"! First alternative; uses dip"
"[ 1 + ] [ 1 - ] [ 2 * ] tri*"
}
"A generalization of the above combinators to any number of quotations can be found in " { $link "combinators" } "."
+ $nl
{ $subsection "spread-shuffle-equivalence" } ;
ARTICLE: "apply-combinators" "Apply combinators"
"The apply combinators apply a single quotation to multiple values. The " { $snippet "@" } " suffix signifies application."
$nl
"Two quotations:"
- { $subsection bi@ }
- { $subsection 2bi@ }
+ { $subsections bi@ 2bi@ }
"Three quotations:"
- { $subsection tri@ }
- { $subsection 2tri@ }
+ { $subsections tri@ 2tri@ }
"A pair of utility words built from " { $link bi@ } ":"
- { $subsection both? }
- { $subsection either? } ;
+ { $subsections both? either? } ;
ARTICLE: "retainstack-combinators" "Retain stack combinators"
"Sometimes an additional storage area is needed to hold objects. The " { $emphasis "retain stack" } " is an auxilliary stack for this purpose. Objects can be moved between the data and retain stacks using a set of combinators."
$nl
"The dip combinators invoke the quotation at the top of the stack, hiding the values underneath:"
- { $subsection dip }
- { $subsection 2dip }
- { $subsection 3dip }
- { $subsection 4dip }
+ { $subsections dip 2dip 3dip 4dip }
"The keep combinators invoke a quotation which takes a number of values off the stack, and then they restore those values:"
- { $subsection keep }
- { $subsection 2keep }
- { $subsection 3keep } ;
+ { $subsections keep 2keep 3keep } ;
ARTICLE: "curried-dataflow" "Curried dataflow combinators"
"Curried cleave combinators:"
- { $subsection bi-curry }
- { $subsection tri-curry }
+ { $subsections bi-curry tri-curry }
"Curried spread combinators:"
- { $subsection bi-curry* }
- { $subsection tri-curry* }
+ { $subsections bi-curry* tri-curry* }
"Curried apply combinators:"
- { $subsection bi-curry@ }
- { $subsection tri-curry@ }
+ { $subsections bi-curry@ tri-curry@ }
{ $see-also "dataflow-combinators" } ;
ARTICLE: "compositional-examples" "Examples of compositional combinator usage"
ARTICLE: "compositional-combinators" "Compositional combinators"
"Certain combinators transform quotations to produce a new quotation."
- { $subsection "compositional-examples" }
+ { $subsections "compositional-examples" }
"Fundamental operations:"
- { $subsection curry }
- { $subsection compose }
+ { $subsections curry compose }
"Derived operations:"
- { $subsection 2curry }
- { $subsection 3curry }
- { $subsection with }
- { $subsection prepose }
+ { $subsections 2curry 3curry with prepose }
"These operations run in constant time, and in many cases are optimized out altogether by the " { $link "compiler" } ". " { $link "fry" } " are an abstraction built on top of these operations, and code that uses this abstraction is often clearer than direct calls to the below words."
$nl
"Curried dataflow combinators can be used to build more complex dataflow by combining cleave, spread and apply patterns in various ways."
- { $subsection "curried-dataflow" }
+ { $subsections "curried-dataflow" }
"Quotations also implement the sequence protocol, and can be manipulated with sequence words; see " { $link "quotations" } ". However, such runtime quotation manipulation will not be optimized by the optimizing compiler." ;
ARTICLE: "booleans" "Booleans"
"In Factor, any object that is not " { $link f } " has a true value, and " { $link f } " has a false value. The " { $link t } " object is the canonical true value."
- { $subsection f }
- { $subsection t }
+ { $subsections f t }
"A union class of the above:"
- { $subsection boolean }
+ { $subsections boolean }
"There are some logical operations on booleans:"
- { $subsection >boolean }
- { $subsection not }
- { $subsection and }
- { $subsection or }
- { $subsection xor }
+ { $subsections
+ >boolean
+ not
+ and
+ or
+ xor
+ }
"Boolean values are most frequently used for " { $link "conditionals" } "."
{ $heading "The f object and f class" }
"The " { $link f } " object is the unique instance of the " { $link f } " class; the two are distinct objects. The latter is also a parsing word which adds the " { $link f } " object to the parse tree at parse time. To refer to the class itself you must use " { $link POSTPONE: POSTPONE: } " or " { $link POSTPONE: \ } " to prevent the parsing word from executing."
ARTICLE: "conditionals" "Conditional combinators"
"The basic conditionals:"
- { $subsection if }
- { $subsection when }
- { $subsection unless }
+ { $subsections if when unless }
"Forms abstracting a common stack shuffle pattern:"
- { $subsection if* }
- { $subsection when* }
- { $subsection unless* }
+ { $subsections if* when* unless* }
"Another form abstracting a common stack shuffle pattern:"
- { $subsection ?if }
+ { $subsections ?if }
"Sometimes instead of branching, you just need to pick one of two values:"
- { $subsection ? }
+ { $subsections ? }
"Two combinators which abstract out nested chains of " { $link if } ":"
- { $subsection cond }
- { $subsection case }
+ { $subsections cond case }
{ $subsection "conditionals-boolean-equivalence" }
{ $see-also "booleans" "bitwise-arithmetic" both? either? } ;
ARTICLE: "dataflow-combinators" "Data flow combinators"
"Data flow combinators pass values between quotations:"
- { $subsection "retainstack-combinators" }
- { $subsection "cleave-combinators" }
- { $subsection "spread-combinators" }
- { $subsection "apply-combinators" }
+ { $subsections
+ "retainstack-combinators"
+ "cleave-combinators"
+ "spread-combinators"
+ "apply-combinators"
+ }
{ $see-also "curried-dataflow" } ;
ARTICLE: "combinators-quot" "Quotation construction utilities"
"Some words for creating quotations which can be useful for implementing method combinations and compiler transforms:"
- { $subsection cond>quot }
- { $subsection case>quot }
- { $subsection alist>quot } ;
+ { $subsections cond>quot case>quot alist>quot } ;
ARTICLE: "call-unsafe" "Unsafe combinators"
"Unsafe calls declare an effect statically without any runtime checking:"
- { $subsection call-effect-unsafe }
- { $subsection execute-effect-unsafe } ;
+ { $subsections call-effect-unsafe execute-effect-unsafe } ;
ARTICLE: "call" "Fundamental combinators"
"The most basic combinators are those that take either a quotation or word, and invoke it immediately."
"There are two sets of combinators; they differ in whether or not the stack effect of the expected code is declared."
$nl
"The simplest combinators do not take an effect declaration. The compiler checks the stack effect at compile time, rejecting the program if this cannot be done:"
- { $subsection call }
- { $subsection execute }
+ { $subsections call execute }
"The second set of combinators takes an effect declaration. Note that the opening parenthesis is actually part of the word name; these are parsing words, and they read a stack effect until the corresponding closing parenthesis. The stack effect of the quotation or word is then checked at runtime:"
- { $subsection POSTPONE: call( }
- { $subsection POSTPONE: execute( }
+ { $subsections POSTPONE: call( POSTPONE: execute( }
"The above are syntax sugar. The underlying words are a bit more verbose but allow non-constant effects to be passed in:"
- { $subsection call-effect }
- { $subsection execute-effect }
+ { $subsections call-effect execute-effect }
"The combinator variants that do not take an effect declaration can only be used if the compiler is able to infer the stack effect by other means. See " { $link "inference-combinators" } "."
{ $subsection "call-unsafe" }
{ $see-also "effects" "inference" } ;
ARTICLE: "combinators" "Combinators"
"A central concept in Factor is that of a " { $emphasis "combinator" } ", which is a word taking code as input."
- { $subsection "call" }
- { $subsection "dataflow-combinators" }
- { $subsection "conditionals" }
- { $subsection "looping-combinators" }
- { $subsection "compositional-combinators" }
- { $subsection "combinators.short-circuit" }
- { $subsection "combinators.smart" }
+ { $subsections
+ "call"
+ "dataflow-combinators"
+ "conditionals"
+ "looping-combinators"
+ "compositional-combinators"
+ "combinators.short-circuit"
+ "combinators.smart"
+ "combinators-quot"
+ "generalizations"
+ }
"More combinators are defined for working on data structures, such as " { $link "sequences-combinators" } " and " { $link "assocs-combinators" } "."
- { $subsection "combinators-quot" }
- { $subsection "generalizations" }
{ $see-also "quotations" } ;
ABOUT: "combinators"
projects / factor.git / commitdiff