Red by Example - an accessible reference by example

Last update on 29-Nov-2022
This is now a community project, you can collaborate on GitHub.

index

index     parse     vid     series     draw     help     about     links     contact     

GUI: VID, View words in alphanumerical order

across                  all-over                aqua                    area                    
at backdrop base beige
below black blue bold
bottom box brick brown
button camera caret-to-offset center
center-face check coal coffee
crimson cyan data default!
disabled distance? do do-events
draw draw drop-down drop-list
dump-face event? extra facet
field find-flag? focus font
font-color font-name font-size foreach-face
forest get-scroller glass gold
gray green group-box h1
h2 h3 h4 h5
handle! handle? hidden hint
image image! image? insert-event-func
italic ivory khaki layout
leaf left linen link-sub-to-parent
link-tabs-to-parent loose magenta make-face
maroon metrics? middle mint
navy no-wrap offset-to-caret offset-to-char
offset? oldrab olive on-alt-down
on-alt-up on-aux-down on-aux-up on-change
on-click on-close on-create on-dbl-click
on-detect on-down on-drag on-drag-start
on-drop on-enter on-face-deep-change* on-focus
on-key on-key-down on-key-up on-menu
on-mid-down on-mid-up on-move on-moving
on-over on-pan on-parse-event on-press-tap
on-resize on-resizing on-rotate on-select
on-time on-two-tap on-unfocus on-up
on-zoom orange origin overlap?
pad panel papaya para
pewter pink progress purple
radio rate react reblue
rebolor red remove-event-func remove-event-func
remove-reactor request-dir request-file request-font
return rich-text right rtd-layout
screen select set-flag set-focus
show sienna silver size-text
sky slider snow space
style tab-panel tanned teal
text text-list title top
transparent underline unview view
violet water wheat white
window with wrap yello
yellow
top alphanumeric-index category-index

Parse dialect words in alphanumerical order

copy                    skip                    
top alphanumeric-index category-index

Draw Dialect words in alphanumerical order

box                     fill-pen                line                    pen                     
top alphanumeric-index category-index

Red words in alphanumerical order

%                       *                       **                      +                       
- / // <
<< <= <> =
== =? > >=
>> >>> ? ??
a-an about absolute acos
action! action? add alert
all all-word! all-word? also
alter and and~ any
any-block! any-block? any-function! any-function?
any-list! any-list? any-object! any-object?
any-path! any-path? any-string! any-string?
any-type! any-word! any-word? append
arccosine arcsine arctangent arctangent2
as as-color as-ipv4 as-pair
as-rgba asin ask at
atan atan2 attempt average
back binary! binary? bind
bitset! bitset? block! block?
body-of break browse call
case catch cause-error cd
change change-dir char! char?
charset checksum clean-path clear
clear-reactions collect comma comment
complement complement? compose construct
context context? continue copy
cos cosine CR create-dir
datatype! datatype? date! date?
dbl-quote debase decompress dehex
delete difference dir dir?
dirize divide do do-safe
do-thru does dot either
ellipsize-at email! email? empty?
enbase equal? error! error?
escape eval-set-path even? event!
event? exclude exists-thru? exists?
exit exp expand expand-directives
extend external! extract extract-boot-args
face? false fetch-help fifth
file! file? find find-flag?
first flip-exe-flag float! float?
forall foreach forever form
fourth func function function!
function? get get-current-dir get-env
get-path! get-path? get-word! get-word?
greater-or-equal? greater? halt has
hash! hash? head head?
help help-string hex-to-rgb if
immediate! immediate? in index?
input insert integer! integer?
internal! intersect issue! issue?
keys-of last last-lf? length?
lesser-or-equal? lesser? lf list-dir
list-env lit-path! lit-path? lit-word!
lit-word? ll load load-thru
log-10 log-2 log-e logic!
logic? loop lowercase ls
make make-dir map! map?
math max min mod
modify modulo mold move
multiply NaN? native! native?
needs negate negative? new-line
new-line? newline next no
none none! none? normalize-dir
not not-equal? now null
number! number? object object!
object? odd? off offset?
on on-face-deep-change* on-parse-event op!
op? or or~ os-info
overlap? pad pair! pair?
paren! paren? parse parse-trace
path! path-thru path? percent!
percent? pi pick poke
positive? power prin print
probe put pwd q
query quit quit-return quote
random react react? read
read-clipboard read-thru rebol recycle
red-complete-input reduce refinement! refinement?
reflect rejoin remainder remove
remove-each repeat repend replace
return reverse round routine
routine! routine? same? save
scalar! scalar? second select
series! series? set set-current-dir
set-env set-path! set-path? set-quiet
set-word! set-word? shift shift-left
shift-logical shift-right sign? sin
sine size? skip slash
sort source sp space
spec-of split split-path sqrt
square-root stats stop-reactor strict-equal?
string! string? subtract suffix?
sum swap switch tab
tag! tag? tail tail?
take tan tangent third
throw time! time? to
to-binary to-bitset to-block to-char
to-date to-email to-file to-float
to-get-path to-get-word to-hash to-hex
to-image to-integer to-issue to-lit-path
to-lit-word to-local-date to-local-file to-logic
to-map to-none to-pair to-paren
to-path to-percent to-red-file to-refinement
to-set-path to-set-word to-string to-tag
to-time to-tuple to-typeset to-unset
to-url to-UTC-date to-word trim
true try tuple! tuple?
type? typeset! typeset? union
unique unless unset unset!
unset? until uppercase url!
url? value? values-of vector!
vector? wait what what-dir
while within? word! word?
words-of write write-clipboard write-stdout
xor xor~ yes zero?
top alphanumeric-index category-index

Master index of categories

Bases of Numbers              Bit manipulation              Boolean                       
Casting Types Comparison Conditional branching
Console Constants Create
Conversion Colors Compression
Directories Documentation Datatypes
Draw Dialect Date/Time Error
Evaluation Exiting Events
Files Formatting Functions
GUI: VID, View Help & Debug Input
Iteration Logic Maps
Math Macros Network
Objects Output Parse
Parse dialect Reflection Reactivity
Series Sets Special Purpose
String manipulation System Related Type Checking
Unknown URL/Internet Word Manipulation
top alphanumeric-index category-index

Category: Bases of Numbers

debase                  enbase                  to-binary               to-hex                  
top alphanumeric-index category-index

Category: Bit manipulation

<<                      >>                      >>>                     and                     
and~ complement not or
or~ shift shift-left shift-logical
shift-right to-bitset xor xor~
top alphanumeric-index category-index

Category: Boolean

all                     and                     and~                    any                     
false no none not
off on or or~
to-logic true yes
top alphanumeric-index category-index

Category: Casting Types

as-color                as-ipv4                 as-pair                 as-rgba                 
to
top alphanumeric-index category-index

Category: Comparison

<                       <=                      <>                      =                       
== =? > >=
all and and~ any
equal? greater-or-equal? greater? lesser-or-equal?
lesser? negative? not not-equal?
or or~ positive? same?
strict-equal? zero?
top alphanumeric-index category-index

Category: Conditional branching

case                    catch                   either                  if                      
switch throw unless
top alphanumeric-index category-index

Category: Console

prin                    print                   probe                   
top alphanumeric-index category-index

Category: Constants

comma                   CR                      dbl-quote               dot                     
escape false lf newline
no none null on
pi slash sp space
tab true yes
top alphanumeric-index category-index

Category: Create

make                    
top alphanumeric-index category-index

Category: Conversion

as                      as-color                as-ipv4                 as-pair                 
as-rgba debase dehex dirize
enbase form hex-to-rgb modify
to to-binary to-bitset to-block
to-char to-date to-email to-file
to-float to-get-path to-get-word to-hash
to-hex to-image to-integer to-issue
to-lit-path to-lit-word to-local-date to-local-file
to-logic to-map to-none to-pair
to-paren to-path to-percent to-red-file
to-refinement to-set-path to-set-word to-string
to-tag to-time to-tuple to-typeset
to-unset to-url to-UTC-date to-word
top alphanumeric-index category-index

Category: Colors

aqua                    beige                   black                   blue                    
brick brown coal coffee
crimson cyan forest glass
gold gray green ivory
khaki leaf linen magenta
maroon mint navy oldrab
olive orange papaya pewter
pink purple reblue rebolor
red sienna silver sky
snow tanned teal transparent
violet water wheat white
yello yellow as-color as-rgba
hex-to-rgb tuple!
top alphanumeric-index category-index

Category: Compression

decompress              
top alphanumeric-index category-index

Category: Directories

request-dir             change-dir              clean-path              delete                  
dir dir? dirize exists?
get-current-dir list-dir ll normalize-dir
pwd read split-path suffix?
write
top alphanumeric-index category-index

Category: Documentation

?                       ??                      comment                 fetch-help              
help help-string source what
top alphanumeric-index category-index

Category: Datatypes

default!                image!                  action!                 all-word!               
any-block! any-function! any-list! any-object!
any-path! any-string! any-type! any-word!
binary! bitset! block! char!
datatype! email! error! event!
external! file! float! function!
get-path! get-word! hash! integer!
internal! issue! lit-path! lit-word!
logic! make map! native!
none! number! object! op!
pair! paren! path! percent!
refinement! routine! scalar! series!
set-path! set-word! string! tag!
time! to-typeset tuple! typeset!
unset! url! vector! word!
top alphanumeric-index category-index

Category: Draw Dialect

box                     fill-pen                line                    pen                     
top alphanumeric-index category-index

Category: Date/Time

date!                   date?                   now                     to-date                 
to-local-date to-time to-UTC-date
top alphanumeric-index category-index

Category: Error

attempt                 catch                   cause-error             error?                  
throw try
top alphanumeric-index category-index

Category: Evaluation

also                    do                      do-safe                 do-thru                 
eval-set-path reduce
top alphanumeric-index category-index

Category: Exiting

exit                    halt                    q                       quit                    
quit-return return
top alphanumeric-index category-index

Category: Events

on-alt-down             on-alt-up               on-aux-down             on-aux-up               
on-change on-click on-close on-create
on-dbl-click on-detect on-down on-drag
on-drag-start on-drop on-enter on-face-deep-change*
on-focus on-key on-key-down on-key-up
on-menu on-mid-down on-mid-up on-move
on-moving on-over on-pan on-parse-event
on-press-tap on-resize on-resizing on-rotate
on-select on-time on-two-tap on-unfocus
on-up on-zoom
top alphanumeric-index category-index

Category: Files

request-file            cd                      change-dir              clean-path              
create-dir delete dir dir?
dirize exists-thru? exists? file!
file? get-current-dir list-dir ll
load load-thru ls make-dir
needs normalize-dir path-thru path?
query read read-thru save
set-current-dir size? split-path suffix?
to-file to-local-file to-red-file what-dir
write
top alphanumeric-index category-index

Category: Formatting

form                    mold                    pad                     
top alphanumeric-index category-index

Category: Functions

body-of                 does                    exit                    func                    
function function! has keys-of
native? routine routine! routine?
top alphanumeric-index category-index

Category: GUI: VID, View

across                  all-over                aqua                    area                    
at backdrop base beige
below black blue bold
bottom box brick brown
button camera caret-to-offset center
center-face check coal coffee
crimson cyan data default!
disabled distance? do do-events
draw draw drop-down drop-list
dump-face event? extra facet
field find-flag? focus font
font-color font-name font-size foreach-face
forest get-scroller glass gold
gray green group-box h1
h2 h3 h4 h5
handle! handle? hidden hint
image image! insert-event-func italic
ivory khaki layout leaf
left linen link-sub-to-parent link-tabs-to-parent
loose magenta make-face maroon
metrics? middle mint navy
no-wrap offset-to-caret offset-to-char offset?
oldrab olive on-alt-down on-alt-up
on-aux-down on-aux-up on-change on-click
on-close on-create on-dbl-click on-detect
on-down on-drag on-drag-start on-drop
on-enter on-face-deep-change* on-focus on-key
on-key-down on-key-up on-menu on-mid-down
on-mid-up on-move on-moving on-over
on-pan on-parse-event on-press-tap on-resize
on-resizing on-rotate on-select on-time
on-two-tap on-unfocus on-up on-zoom
orange origin overlap? pad
panel papaya para pewter
pink progress purple radio
rate react reblue rebolor
red remove-event-func remove-event-func remove-reactor
request-dir request-file request-font return
rich-text right rtd-layout screen
select set-flag set-focus show
sienna silver size-text sky
slider snow space style
tab-panel tanned teal text
text-list title top transparent
underline unview view violet
water wheat white window
with wrap yello yellow
face? needs on-face-deep-change* overlap?
set-quiet to-image
top alphanumeric-index category-index

Category: Help & Debug

?                       ??                      about                   fetch-help              
help help-string source what
top alphanumeric-index category-index

Category: Input

alert                   ask                     input                   last-lf?                
load load-thru needs path-thru
read read-thru red-complete-input
top alphanumeric-index category-index

Category: Iteration

foreach-face            break                   continue                forall                  
foreach forever loop repeat
until while
top alphanumeric-index category-index

Category: Logic

all                     and                     and~                    any                     
logic! not or or~
top alphanumeric-index category-index

Category: Maps

extend                  put                     
top alphanumeric-index category-index

Category: Math

%                       *                       **                      +                       
- / // absolute
acos add arccosine arcsine
arctangent arctangent2 asin atan
atan2 average cos cosine
divide even? exp float!
integer! log-10 log-2 log-e
math max min mod
modulo multiply NaN? negate
number! odd? pi power
random remainder round sign?
sin sine sqrt square-root
subtract sum tan tangent
to-float to-integer within?
top alphanumeric-index category-index

Category: Macros

expand                  expand-directives       
top alphanumeric-index category-index

Category: Network

checksum                to-email                
top alphanumeric-index category-index

Category: Objects

bind                    construct               context                 extend                  
in object path! path?
top alphanumeric-index category-index

Category: Output

last-lf?                new-line?               prin                    print                   
write write-clipboard write-stdout
top alphanumeric-index category-index

Category: Parse

on-parse-event          parse                   parse-trace             
top alphanumeric-index category-index

Category: Parse dialect

copy                    skip                    
top alphanumeric-index category-index

Category: Reflection

keys-of                 reflect                 spec-of                 values-of               
words-of
top alphanumeric-index category-index

Category: Reactivity

react                   clear-reactions         react                   react?                  
stop-reactor
top alphanumeric-index category-index

Category: Series

alter                   append                  at                      back                    
change clear collect compose
copy empty? exclude extract
fifth find first fourth
head head? index? insert
last length? move new-line
next offset? path! path?
pick poke rejoin remove
remove-each repend replace reverse
second select skip sort
swap tail tail? take
third to-hash to-map union
unique
top alphanumeric-index category-index

Category: Sets

charset                 difference              intersect               union                   
unique
top alphanumeric-index category-index

Category: Special Purpose

also                    
top alphanumeric-index category-index

Category: String manipulation

a-an                    alter                   append                  at                      
back change clear collect
compose copy ellipsize-at empty?
exclude extract fifth find
first fourth head head?
index? insert last length?
lowercase move next pad
pick poke rejoin remove
replace reverse second select
skip sort split swap
tail tail? third to-string
trim uppercase
top alphanumeric-index category-index

Category: System Related

call                    extract-boot-args       flip-exe-flag           get-env                 
halt list-env os-info quit
quit-return read-clipboard rebol recycle
routine set-env stats wait
write-clipboard write-stdout
top alphanumeric-index category-index

Category: Type Checking

event?                  handle!                 image?                  action?                 
all-word? any-block? any-function? any-list?
any-object? any-path? any-string? any-word?
binary? bitset? block? char?
complement? context? datatype? date?
dir? email? empty? equal?
error? event? face? file?
find-flag? float? function? get-path?
get-word? hash? immediate! immediate?
integer? issue? lit-path? lit-word?
logic? map? native? new-line?
none? not-equal? number? object?
op? pair? paren? path?
percent? refinement? routine? same?
scalar? series? set-path? set-word?
string? tag? time? tuple?
type? typeset? url? value?
vector? word?
top alphanumeric-index category-index

Category: Unknown

top     alphanumeric-index     category-index

Category: URL/Internet

as-ipv4                 browse                  dehex                   do-thru                 
email! exists-thru? load-thru path-thru
read read-thru to-email to-url
url! url?
top alphanumeric-index category-index

Category: Word Manipulation

get                     quote                   set                     to-get-word             
to-lit-word to-set-word to-word unset
unset! unset?
top alphanumeric-index category-index


%          type:  op!--    Cats: Math
The infix word % returns what is left over when argument 1 is divided 
by argument 2.

Arguments can have those types:
number! char! pair! tuple! vector! time!
Examples
red>> 3 % 2
== 1

red>> 3.5 % 2
== 1.5

red>> 3.6 % 2.2
== 1.4

red>> 11x19 % 3
== 2x1

red>> 11x19 % 3x4
== 2x3

top alphanumeric-index category-index



*          type:  op!--    Cats: Math
The infix word * multiplies its two operands.
It is the equivalent of the multiply function.

It operates on these types:
number! char! pair! tuple! vector!

In Red, infix operators are evaluated from left to right, with no precedence.
You may use parentheses ( ) to change the order of evaluation.

The word * is a Red word and thus needs to be separated by whitespace.

In general, the type of the result is the same type as the first operand,
where this is sensible. Errors will result when the types are incompatible.

Note the result when vectors of different lengths are multiplied.

When we multiply two vector!s, the result is a freshly allocated vector!.

When we multiply a vector! with a number!, the original vector!
will be modified.
Examples
red>> 2 * 3.7
== 7.4

red>> 3 * 1.4.8
== 1.12.8

red>> 4 * 10x20
== 40x80

red>> v1: make vector![2 3 4 5]
== make vector! [2 3 4 5]

red>> v2: make vector! [22 55]
== make vector! [22 55]

red>> v1 * v2
== make vector! [44 165]

red>> v1
== make vector! [2 3 4 5]
; v1 unchanged

red>> v1 * 9
== make vector! [18 27 36 45]

red>> v1
== make vector! [18 27 36 45]
; v1 changed

red>> 3 * v1
*** Script error: vector type is not allowed here
*** Where: *

top alphanumeric-index category-index



**          type:  op!--    Cats: Math
The infix word ** raises argument 1 to the power argument 2.
Examples
red>> 2 ** 2
== 4

red>> 2 ** 10
== 1024

red>> 2 ** -1
== 0.5

red>> 2 ** -10
== 0.0009765625

red>> -2 ** 4
== 16

red>> -2 ** 3
== -8

red>> 2 ** 0.5
== 1.414213562373095

red>> 2 ** -0.5
== 0.7071067811865476

top alphanumeric-index category-index



+          type:  op!--    Cats: Math
The infix word + adds its two operands.
It is the equivalent of the add function.

It operates on these types:
number! char! pair! tuple! vector! time! date!

In Red, infix operators are evaluated from left to right, with no precedence.
You may use parentheses ( ) to change the order of evaluation.

In general, the type of the result is the same type as the first operand,
where this is sensible. Errors will result when the types are incompatible.
See examples.

Note the result when vectors of different lengths are added.

The operator + is a Red word and thus needs to be separated by whitespace.

When we add two vector!s, the result is a freshly allocated vector!.
When we add a number! to a vector!, the original vector! will be modified.
Examples
red>> 1 + 3.7
== 4.7

red>> 3 + 100x200
== 103x203

red>> v1: make Vector![3 2 1 4]
== make vector! [3 2 1 4]

red>> v2: make vector![100 200]
== make vector! [100 200]

red>> v1 + v2
== make vector! [103 202]

red>> v1
== make vector! [3 2 1 4]
; v1 unchanged

red>> v2 + v1
== make vector! [103 202]

red>> v1 - 22
== make vector! [-19 -20 -21 -18]
; v1 altered

red>> v1
== make vector! [-19 -20 -21 -18]

red>> 3 + v1
*** Script error: vector type is not allowed here
*** Where: +

top alphanumeric-index category-index



-          type:  op!--    Cats: Math
The infix word - subtracts its second operand from its first operand.
It is the equivalent of the subtract function.

It operates on these types:
number! char! pair! tuple! vector! time! date!

In Red, infix operators are evaluated from left to right, with no precedence.
You may use parentheses ( ) to change the order of evaluation.

The operator - is a Red word and thus needs to be separated by whitespace.

In general, the type of the result is the same type as the first operand,
where this is sensible. Errors will result when the types are incompatible.

Note the result when vectors of different lengths are subtracted.

When we subtract 2 vectors, the result is a freshly allocated vector.
When we subtract a number from a vector, the original vector will be modified.
Examples
; -------------------------------------------------------------------------
; Subtract float! from integer!
; -------------------------------------------------------------------------


red>> 3 - 1.4
1.6

; -------------------------------------------------------------------------
; Subtract pair! from integer! not possible
; -------------------------------------------------------------------------


red>> 3 - 100x100
*** Script error: - does not allow pair for its value2 argument
*** Where: -

; -------------------------------------------------------------------------
; Subtract integer! from pair! is possible
; -------------------------------------------------------------------------


red>> 100x200 - 3
== 97x197

; -------------------------------------------------------------------------
; Subtract vector!s
; -------------------------------------------------------------------------


red>> v1: make vector! [3 2 1 4]
== make vector! [3 2 1 4]

red>> v2: make vector! [100 200]
== make vector! [100 200]

red>> v1 - v2
== make vector! [-97 -198]

red>> v2 - v1
== make vector! [97 198]

red>> v2
== make vector! [100 200]
; v2 is unchanged

red>> v1 - 22
== make vector! [-19 -20 -21 -18]

red>> v1
== make vector! [-19 -20 -21 -18]
; v1 is altered!

red>> 22 - v1
*** Script error: vector type is not allowed here
*** Where: -

top alphanumeric-index category-index



/          type:  op!--    Cats: Math
The infix word / divides its operands giving a quotient.
It is the equivalent of the divide function.

It operates on these types:
number! char! pair! tuple! vector!

In Red, infix operators are evaluated from left to right, with no precedence.
You may use parentheses ( ) to change the order of evaluation.

/ is a Red word and thus needs to be separated by whitespace.

When one of the operands is a float!, the result is a float!.

When both operands are integer!, the result is integer!,
truncated towards zero.

Otherwise, the type of the result is the same type as the first operand,
where this is sensible. Errors will result when the types are incompatible.

Note the result when vector!s of different lengths are divided.

When we divide two vector!s, the result is a freshly allocated vector!.
When we divide a vector! by a number!, the original vector! will be modified.
Examples
red>> 9 / 3
== 3

red>> 9.0 / 3
== 3.0

red>> 10 / 11
== 0

red>> -11 / 4
== -2

red>> 100x30 / 5
== 20x6

red>> 100x40 / 2x4
== 50x10

red>> 3.9.19 / 3
== 1.3.6

red>> v1: make vector![100 200 300 400]
== make vector! [100 200 300 400]

red>> v2: make vector![5 5 10]
== make vector! [5 5 10]

red>> v1 / v2
== make vector! [20 40 30]

red>> v1
== make vector! [100 200 300 400]
; v1 unchanged

red>> v1 / 5
== make vector! [20 40 60 80]

red>> v1
== make vector! [20 40 60 80]
; v1 changed

red>> 5 / v1
*** Script error: vector type is not allowed here
*** Where: /

top alphanumeric-index category-index



//          type:  op!--    Cats: Math
The infix word // is the nonnegative remainder oparator,
that returns what is left over when the first argument is divided
by the second.

Has two arguments of type:
number! char! pair! tuple! vector!

There is also a functional version, named remainder.

If the first argument is positive, then the remainder is positive.

If the first argument is negative, then the remainder is also positive,
as in -5 // 4, which results in 3.

If the first argument is zero, then the remainder is also zero.

If the second argument is zero, a run-time error occurs.
Examples
red>> 5 // 4
== 1
red>> 5 // 5
== 0
red>> 5 // 6
== 5
red>> -5 // 4
== 3
red>> 10 // 3.3
== 0.1000000000000005
red>> 5x10 // 4
*** Internal error: reserved for future use (or not yet implemented)
*** Where: >
red>> remainder 5x10 4
== 1x2
red>> make vector![5 5 10] // 4
*** Script error: % does not allow block for its value1 argument
*** Where: %

top alphanumeric-index category-index



across          type:  GUI: VID, View!--    Cats: GUI: VID, View
The VID dialect word across is used to position GUI elements following that
word at the right hand side of the previous GUI element.
Examples
Red [
needs: 'view
]

view [
across
text "Line 1"
text "Line 2"
]

vid-across.png

top alphanumeric-index category-index



all-over          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



aqua          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word aqua is a color that can be used for GUI elements.

It is a tuple! of value 40.100.130
Examples
view [
text 100x50 aqua " "
]

vid-aqua.png

top alphanumeric-index category-index



area          type:  GUI: VID, View!--    Cats: GUI: VID, View
Provides a multi-line rectangle where text can be entered, selected, edited, 
copied, pasted. We can choose the font-size, color, font, etc. Rich text
is not supported.

The default event-handler is on-change.

The text in the area can be accessed via the /text refinement.

Examples:

;-- an area with a size, specified font, and initial text.
a1: area white font [name: "Consolas" size: 12 color: black]
{area with
some text
}
120x70 [print "a1 changed"] ;-- on-change


There is a complete VID example in:

http://www.red-by-example.org/vid-text-red.html


There is an introduction to VID at:

http://www.red-by-example.org/vid.html


Its official View documentation is at:

https://doc.red-lang.org/en/view.html#_area


top alphanumeric-index category-index



at          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



backdrop          type:  GUI: VID, View!--    Cats: GUI: VID, View
Sets the background color of the container face.

Argument

backdrop

- name or value of a color (word! tuple! issue!).

Examples

view [
;-- set color, size, and title for window
backdrop green ;-- green window
size 300x200
title "Demo Window"
space 100x70 ;-- bigger horizontal spacing
b1: button "Hello"
b2: button "Goodbye"
return
]




top alphanumeric-index category-index



base          type:  GUI: VID, View!--    Cats: GUI: VID, View
The most basic face type, but also the most versatile one. By default, it 
will only display a background of color! 128.128.128. (Grey). It
provides transparency, and can be used for drawing.

The default event is on-down

VID Example:

base 140x140 %country.png ;-- supply image file name

There is a complete VID example in:

http://www.red-by-example.org/vid-misc-faces-red.html


There is an introduction to VID at:

http://www.red-by-example.org/vid.html


Its official View documentation is at:

https://doc.red-lang.org/en/view.html#_base



top alphanumeric-index category-index



beige          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word beige is a color that can be used for GUI elements.

It is a tuple! of value 255.228.196
Examples
view [
text 100x50 beige " "
]

vid-beige.png

top alphanumeric-index category-index



below          type:  GUI: VID, View!--    Cats: GUI: VID, View
The function below is used to position GUI elements following that
word below the previous GUI element.
Examples
Red [
needs: 'view
]

view [
below
text "Line 1"
text "Line 2"
]

vid-below.png

top alphanumeric-index category-index



black          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word black is a color that can be used for GUI elements.

It is a tuple! of value 0.0.0
Examples
view [
text 100x50 black " "
]

vid-black.png

top alphanumeric-index category-index



blue          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word blue is a color that can be used for GUI elements.

It is a tuple! of value 0.0.255
Examples
view [
text 100x50 blue " "
]

vid-blue.png

top alphanumeric-index category-index



bold          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



bottom          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



box          type:  GUI: VID, View!--    Cats: GUI: VID, View
This is a VID style.  It is a base type, but with  a default 
transparent color.

The default event is on-down

There is a complete VID example in:

http://www.red-by-example.org/vid-misc-faces-red.html


There is an introduction to VID at:

http://www.red-by-example.org/vid.html


top alphanumeric-index category-index



brick          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word brick is a color that can be used for GUI elements.

It is a tuple! of value 178.34.34
Examples
view [
text 100x50 brick " "
]

vid-brick.png

top alphanumeric-index category-index



brown          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word brown is a color that can be used for GUI elements.

It is a tuple! of value 139.69.19
Examples
view [
text 100x50 brown " "
]

vid-brown.png

top alphanumeric-index category-index



button          type:  GUI: VID, View!--    Cats: GUI: VID, View
A button is used to confirm something, or to simply invoke some 
action.

Note that on-click and on-down do the same thing for a
button.

The default event is on-down.

In VID, here are 2 buttons.

button "Click me" [print "Clicked"] ;-- respond to down

button2: button "Try Me 2" ;-- named button
on-down [button2-down] ;-- respond to down - call a function
on-over [button2-over] ;-- respond to over (hover) - call a
function

There is a complete VID example in:

http://www.red-by-example.org/vid-misc-faces-red.html


There is an introduction to VID at:

http://www.red-by-example.org/vid.html


Its official View documentation is at:

https://doc.red-lang.org/en/view.html#_button



top alphanumeric-index category-index



camera          type:  GUI: VID, View!--    Cats: GUI: VID, View

(Awaiting additional documentation by red-by-example team.)


top alphanumeric-index category-index



caret-to-offset          type:  GUI: VID, View!--    Cats: GUI: VID, View
USAGE:
CARET-TO-OFFSET face pos

DESCRIPTION:
Given a text position, returns the corresponding coordinate relative
to the top-left of the layout box.
CARET-TO-OFFSET is a function! value.

ARGUMENTS:
face [object!]
pos [integer!]

REFINEMENTS:
/lower => lower end offset of the caret.

RETURNS:
[pair!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



center          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



center-face          type:  GUI: VID, View!--    Cats: GUI: VID, View
USAGE:
CENTER-FACE face

DESCRIPTION:
Center a face inside its parent.
CENTER-FACE is a function! value.

ARGUMENTS:
face [object!] "Face to center."

REFINEMENTS:
/x => Center horizontally only.
/y => Center vertically only.
/with => Provide a reference face for centering instead of parent face.
parent [object!] "Reference face."

RETURNS:
Returns the centered face.
[object!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



check          type:  GUI: VID, View!--    Cats: GUI: VID, View
A check provides a check-box, with an optional label.  

The default event is on-change

The boolean state exists in 'data'. Note that 'change' can mean true to
false, or false to true.

Here is a VID example which displays the current state when checked:

check1-changed: function [] [
print ["check1-has changed. Current state is: " check1/data]
]

view [
check1: check "Check me" [check1-changed]
]

There is a complete VID example in:

http://www.red-by-example.org/vid-choice-faces-red.html


There is an introduction to VID at:

http://www.red-by-example.org/vid.html


Its official View documentation is at:

https://doc.red-lang.org/en/view.html#_check



top alphanumeric-index category-index



coal          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word coal is a color that can be used for GUI elements.

It is a tuple! of value 64.64.64
Examples
view [
text 100x50 coal " "
]

vid-coal.png

top alphanumeric-index category-index



coffee          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word coffee is a color that can be used for GUI elements.

It is a tuple! of value 76.26.0
Examples
view [
text 100x50 coffee " "
]

vid-coffee.png

top alphanumeric-index category-index



crimson          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word crimson is a color that can be used for GUI elements.

It is a tuple! of value 220.20.60
Examples
view [
text 100x50 crimson " "
]

vid-crimson.png

top alphanumeric-index category-index



cyan          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word cyan is a color that can be used for GUI elements.

It is a tuple! of value 0.255.255
Examples
view [
text 100x50 cyan " "
]

vid-cyan.png

top alphanumeric-index category-index



data          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



default!          type:  GUI: VID, View!--    Cats: Datatypes, GUI: VID, View
DEFAULT! is a typeset! value: make typeset! [datatype! none! logic! block!
paren! string! file! url! char! integer! float! word! set-word! lit-word!
get-word! refinement! issue! native! action! op! function! path! lit-path!
set-path! get-path! routine! bitset! object! typeset! error! vector! hash!
pair! percent! tuple! map! binary! time! tag! email! handle! date! image!
event!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



disabled          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



distance?          type:  GUI: VID, View!--    Cats: GUI: VID, View
USAGE:
DISTANCE? A B

DESCRIPTION:
Returns the distance between the center of two faces.
DISTANCE? is a function! value.

ARGUMENTS:
A [object!] "First face."
B [object!] "Second face."

RETURNS:
Distance between them.
[float!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



do          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



do-events          type:  GUI: VID, View!--    Cats: GUI: VID, View
USAGE:
DO-EVENTS

DESCRIPTION:
Launch the event loop, blocks until all windows are closed.
DO-EVENTS is a function! value.

REFINEMENTS:
/no-wait => Process an event in the queue and returns at once.

RETURNS:
Returned value from last event.
[logic! word!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



draw          type:  GUI: VID, View!--    Cats: GUI: VID, View
USAGE:
DRAW image cmd

DESCRIPTION:
Draws scalable vector graphics to an image.
DRAW is a function! value.

ARGUMENTS:
image [image! pair!] "Image or size for an image."
cmd [block!] "Draw commands."

REFINEMENTS:
/transparent => Make a transparent image, if pair! spec is used.

RETURNS:
[image!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



draw          type:  GUI: VID, View!--    Cats: GUI: VID, View
USAGE:
DRAW image cmd

DESCRIPTION:
Draws scalable vector graphics to an image.
DRAW is a function! value.

ARGUMENTS:
image [image! pair!] "Image or size for an image."
cmd [block!] "Draw commands."

REFINEMENTS:
/transparent => Make a transparent image, if pair! spec is used.

RETURNS:
[image!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



drop-down          type:  GUI: VID, View!--    Cats: GUI: VID, View
A drop-down represents an edit field with a vertical list of text strings 
displayed in a foldable frame. (i.e. a 'combo'). A vertical scrollbar
appears automatically if the content does not fit the frame.

The default event handler is on-enter.

The drop-down, drop-list, and text-list are related.

A none value for 'selection' is returned if no choice has been made.

The associative-array possibility exists, as in drop-list

It is possible to preset the edit field, which might be used as an initial
selection, or a prompt.

Example in VID:

drop-down1: drop-down "Choose Code" data ["A1" "A2" "B1" "B2"]

There is a complete VID example in:

http://www.red-by-example.org/vid-choice-faces-red.html


There is an introduction to VID at:

http://www.red-by-example.org/vid.html


Its official View documentation is at:

https://doc.red-lang.org/en/view.html#_drop_down


top alphanumeric-index category-index



drop-list          type:  GUI: VID, View!--    Cats: GUI: VID, View
This type represents a vertical list of text strings, displayed in a 
foldable frame. A vertical scrollbar appears automatically if the content
does not fit the frame.

The default event handler is on-change

The drop-down, drop-list, and text-list are related.
A none value for 'selection' is returned if no choice has been made.

A drop-down is similar, but it provides an additional edit field (a
'combo').

The drop-list only displays strings, though the 'data' values can include
other types. This can give an associative-array effect. For example, to
find the postage cost of a letter, we can use this in VID:

postal-drop-list: drop-list data["Basic" 33 "2nd-class" 40 "Priority" 99]

Only the 3 strings are displayed.

Multiplying the selected position by 2 would take us to the integer cost
item.

There is a complete VID example in:

http://www.red-by-example.org/vid-choice-faces-red.html


There is an introduction to VID at:

http://www.red-by-example.org/vid.html


Its official View documentation is at:

https://doc.red-lang.org/en/view.html#_drop_list



top alphanumeric-index category-index



dump-face          type:  GUI: VID, View!--    Cats: GUI: VID, View
See the official View documents:
https://doc.red-lang.org/en/view.html

top alphanumeric-index category-index



event?          type:  GUI: VID, View!--    Cats: GUI: VID, View, Type Checking
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



extra          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



facet          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



field          type:  GUI: VID, View!--    Cats: GUI: VID, View
A field provides single-line data entry.   We can provide an initial text 
value, and provide a different pixel width if the default width is
unsuitable.

The default event is on-enter.

We access the data entered with /text.

VID Examples:

f1: field ;-- default size, empty
f2: field "a field" ;-- default size, shows "a field"
f3: field "Enter name here" 200 ;-- wider

There is a complete VID example in:

http://www.red-by-example.org/vid-text-red.html


There is an introduction to VID at:

http://www.red-by-example.org/vid.html


Its official View documentation is at:

https://doc.red-lang.org/en/view.html#_field



top alphanumeric-index category-index



find-flag?          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



focus          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



font          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



font-color          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



font-name          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



font-size          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



foreach-face          type:  GUI: VID, View!--    Cats: GUI: VID, View, Iteration
USAGE:
FOREACH-FACE face body

DESCRIPTION:
Evaluates body for each face in a face tree matching the condition.
FOREACH-FACE is a function! value.

ARGUMENTS:
face [object!] "Root face of the face tree."
body [block! function!] {Body block (`face` object) or
function `func [face [object!]]`.}

REFINEMENTS:
/with => Filter faces according to a condition.
spec [block! none!] "Condition applied to face object."
/post => Evaluates body for current face after processing its
children.
/sub =>
post? "Do not rebind body and spec, internal use only."
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



forest          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word forest is a color that can be used for GUI elements.

It is a tuple! of value 0.48.0
Examples
view [
text 100x50 forest " "
]

vid-forest.png

top alphanumeric-index category-index



get-scroller          type:  GUI: VID, View!--    Cats: GUI: VID, View
USAGE:
GET-SCROLLER face orientation

DESCRIPTION:
return a scroller object from a face.
GET-SCROLLER is a function! value.

ARGUMENTS:
face [object!]
orientation [word!]

RETURNS:
[object!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



glass          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect provides named colors.  Each color has a tuple! value.  

For example, here we create a brown text element:

view [
text 100x50 brown " "
]


top alphanumeric-index category-index



gold          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word gold is a color that can be used for GUI elements.

It is a tuple! of value 255.205.40
Examples
view [
text 100x50 gold " "
]

vid-gold.png

top alphanumeric-index category-index



gray          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word gray is a color that can be used for GUI elements.

It is a tuple! of value 128.128.128
Examples
view [
text 100x50 gray " "
]

vid-gray.png

top alphanumeric-index category-index



green          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word green is a color that can be used for GUI elements.

It is a tuple! of value 0.255.0
Examples
view [
text 100x50 green " "
]

vid-green.png

top alphanumeric-index category-index



group-box          type:  GUI: VID, View!--    Cats: GUI: VID, View
(Awaiting additional documentation by red-by-example team.)

Possible phasing-out.

top alphanumeric-index category-index



h1          type:  GUI: VID, View!--    Cats: GUI: VID, View
The VID dialect has some defined styles (shortcuts).  The styles h1 h2 h3 
h4 h5 display text of a pre-defined size. The largest is h1. We have:

h1 - a text preset to font-size 32
h2 - a text preset to font-size 26
h3 - a text preset to font-size 22
h4 - a text preset to font-size 17
h5 - a text preset to font-size 13

Here is an example:

h1 "Biggest Text Heading"
message: h3 "Medium-sized yellow heading..." yellow


http://www.red-by-example.org/vid-text-faces-red.html


There is an introduction to VID at:

http://www.red-by-example.org/vid.html


top alphanumeric-index category-index



h2          type:  GUI: VID, View!--    Cats: GUI: VID, View
The VID dialect has some defined styles (shortcuts).  The styles h1 h2 h3 
h4 h5 display text of a pre-defined size. The largest is h1. We have:

h1 - a text preset to font-size 32
h2 - a text preset to font-size 26
h3 - a text preset to font-size 22
h4 - a text preset to font-size 17
h5 - a text preset to font-size 13

Here is an example:

h1 "Biggest Text Heading"
message: h3 "Medium-sized yellow heading..." yellow


http://www.red-by-example.org/vid-text-faces-red.html


There is an introduction to VID at:

http://www.red-by-example.org/vid.html


top alphanumeric-index category-index



h3          type:  GUI: VID, View!--    Cats: GUI: VID, View
The VID dialect has some defined styles (shortcuts).  The styles h1 h2 h3 
h4 h5 display text of a pre-defined size. The largest is h1. We have:

h1 - a text preset to font-size 32
h2 - a text preset to font-size 26
h3 - a text preset to font-size 22
h4 - a text preset to font-size 17
h5 - a text preset to font-size 13

Here is an example:

h1 "Biggest Text Heading"
message: h3 "Medium-sized yellow heading..." yellow


http://www.red-by-example.org/vid-text-faces-red.html


There is an introduction to VID at:

http://www.red-by-example.org/vid.html


top alphanumeric-index category-index



h4          type:  GUI: VID, View!--    Cats: GUI: VID, View
The VID dialect has some defined styles (shortcuts).  The styles h1 h2 h3 
h4 h5 display text of a pre-defined size. The largest is h1. We have:

h1 - a text preset to font-size 32
h2 - a text preset to font-size 26
h3 - a text preset to font-size 22
h4 - a text preset to font-size 17
h5 - a text preset to font-size 13

Here is an example:

h1 "Biggest Text Heading"
message: h3 "Medium-sized yellow heading..." yellow


http://www.red-by-example.org/vid-text-faces-red.html


There is an introduction to VID at:

http://www.red-by-example.org/vid.html


top alphanumeric-index category-index



h5          type:  GUI: VID, View!--    Cats: GUI: VID, View
The VID dialect has some defined styles (shortcuts).  The styles h1 h2 h3 
h4 h5 display text of a pre-defined size. The largest is h1. We have:

h1 - a text preset to font-size 32
h2 - a text preset to font-size 26
h3 - a text preset to font-size 22
h4 - a text preset to font-size 17
h5 - a text preset to font-size 13

Here is an example:

h1 "Biggest Text Heading"
message: h3 "Medium-sized yellow heading..." yellow


http://www.red-by-example.org/vid-text-faces-red.html


There is an introduction to VID at:

http://www.red-by-example.org/vid.html


top alphanumeric-index category-index



handle!          type:  GUI: VID, View!--    Cats: GUI: VID, View, Type Checking
A handle! datatype will be used in the future for opaque OS handles for
graphical objects.
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



handle?          type:  GUI: VID, View!--    Cats: GUI: VID, View
USAGE:
HANDLE? value

DESCRIPTION:
Returns true if the value is this type.
HANDLE? is a function! value.

ARGUMENTS:
value [any-type!]


A handle! datatype will be used in the future for opaque OS handles for
graphical objects.

(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



hidden          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



hint          type:  GUI: VID, View!--    Cats: GUI: VID, View
Displays a hint message if a field is empty, which disappears
when an entry is made.

Argument

a string!

Examples
view [
title "Demo Window"
b1: button "Hello"
b2: button "Goodbye"
return
t1: field hint "Enter name" ;-- hint if nothing entered
]

top alphanumeric-index category-index



image          type:  GUI: VID, View!--    Cats: GUI: VID, View
This is a VID style. It is a base type, but with a default size of 
100x100. It expects an image option.

The default event is on-down

There is a complete VID example in:

http://www.red-by-example.org/vid-misc-faces-red.html


There is an introduction to VID at:

http://www.red-by-example.org/vid.html


top alphanumeric-index category-index



image!          type:  GUI: VID, View!--    Cats: Datatypes, GUI: VID, View

(Awaiting additional documentation by red-by-example team.)
Values of this datatype contain a series! of RGBA values, which represent
pixels in a 2D image. Consult the official Red documentation at:


https://doc.red-lang.org/en/datatypes/image.html


top alphanumeric-index category-index



image?          type:  GUI: VID, View!--    Cats: Type Checking
USAGE:
IMAGE? value

DESCRIPTION:
Returns true if the value is this type.
IMAGE? is a function! value.

ARGUMENTS:
value [any-type!]

See image!

top alphanumeric-index category-index



insert-event-func          type:  GUI: VID, View!--    Cats: GUI: VID, View
See the official View documents:
https://doc.red-lang.org/en/view.html

top alphanumeric-index category-index



italic          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



ivory          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word ivory is a color that can be used for GUI elements.

It is a tuple! of value 255.255.240
Examples
view [
text 100x50 ivory " "
]

vid-ivory.png

top alphanumeric-index category-index



khaki          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word khaki is a color that can be used for GUI elements.

It is a tuple! of value 179.179.126
Examples
view [
text 100x50 khaki " "
]

vid-khaki.png

top alphanumeric-index category-index



layout          type:  GUI: VID, View!--    Cats: GUI: VID, View
USAGE:
LAYOUT spec

DESCRIPTION:
Return a face with a pane built from a VID description.
LAYOUT is a function! value.

ARGUMENTS:
spec [block!] "Dialect block of styles, attributes, and layouts."

REFINEMENTS:
/tight => Zero offset and origin.
/options =>
user-opts [block!] "Optional features in [name: value] format."
/flags =>
flgs [block! word!] "One or more window flags."
/only => Returns only the pane block.
/parent =>
panel [object!]
divides [integer! none!]
/styles => Use an existing styles list.
css [block!] "Styles list.
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



leaf          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word leaf is a color that can be used for GUI elements.

It is a tuple! of value 0.128.0
Examples
view [
text 100x50 leaf " "
]

vid-leaf.png

top alphanumeric-index category-index



left          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



linen          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word linen is a color that can be used for GUI elements.

It is a tuple! of value 250.240.230
Examples
view [
text 100x50 linen " "
]

vid-linen.png

top alphanumeric-index category-index



link-sub-to-parent          type:  GUI: VID, View!--    Cats: GUI: VID, View
USAGE:
LINK-SUB-TO-PARENT face type old new

DESCRIPTION:
Internal Use Only.
LINK-SUB-TO-PARENT is a function! value.

ARGUMENTS:
face [object!]
type [word!]
old
new
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



link-tabs-to-parent          type:  GUI: VID, View!--    Cats: GUI: VID, View
USAGE:
LINK-TABS-TO-PARENT face

DESCRIPTION:
Internal Use Only.
LINK-TABS-TO-PARENT is a function! value.

ARGUMENTS:
face [object!]

REFINEMENTS:
/init => Force /show of first tab.
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



loose          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



magenta          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word magenta is a color that can be used for GUI elements.

It is a tuple! of value 255.0.255
Examples
view [
text 100x50 magenta " "
]

vid-magenta.png

top alphanumeric-index category-index



make-face          type:  GUI: VID, View!--    Cats: GUI: VID, View
USAGE:
MAKE-FACE style

DESCRIPTION:
Make a face from a given style name or example face.
MAKE-FACE is a function! value.

ARGUMENTS:
style [word!] "A face type."

REFINEMENTS:
/spec =>
blk [block!] "Spec block of face options expressed in VID."
/offset =>
xy [pair!] "Offset of the face."
/size =>
wh [pair!] "Size of the face."
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



maroon          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word maroon is a color that can be used for GUI elements.

It is a tuple! of value 128.0.0
Examples
view [
text 100x50 maroon " "
]

vid-maroon.png

top alphanumeric-index category-index



metrics?          type:  GUI: VID, View!--    Cats: GUI: VID, View
USAGE:
METRICS? face type

DESCRIPTION:
Returns a pair! value in the type metrics for the argument face.
METRICS? is a function! value.

ARGUMENTS:
face [object!] "Face object to query."
type [word!] "Metrics type: 'paddings or 'margins."

REFINEMENTS:
/total => Return the addition of metrics along an axis.
axis [word!] "Axis to use for addition: 'x or 'y."
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



middle          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



mint          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word mint is a color that can be used for GUI elements.

It is a tuple! of value 100.136.116
Examples
view [
text 100x50 mint " "
]

vid-mint.png

top alphanumeric-index category-index



navy          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word navy is a color that can be used for GUI elements.

It is a tuple! of value 0.0.128
Examples
view [
text 100x50 navy " "
]

vid-navy.png

top alphanumeric-index category-index



no-wrap          type:  GUI: VID, View!--    Cats: GUI: VID, View
To do by red-by-example team ...


top alphanumeric-index category-index



offset-to-caret          type:  GUI: VID, View!--    Cats: GUI: VID, View
USAGE:
OFFSET-TO-CARET face pt

DESCRIPTION:
Given a coordinate, returns the corresponding caret position.
OFFSET-TO-CARET is a function! value.

ARGUMENTS:
face [object!]
pt [pair!]

RETURNS:
[integer!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



offset-to-char          type:  GUI: VID, View!--    Cats: GUI: VID, View
USAGE:
OFFSET-TO-CHAR face pt

DESCRIPTION:
Given a coordinate, returns the corresponding character position.
OFFSET-TO-CHAR is a function! value.

ARGUMENTS:
face [object!]
pt [pair!]

RETURNS:
[integer!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



offset?          type:  GUI: VID, View!--    Cats: GUI: VID, View
To do by red-by-example team ...


top alphanumeric-index category-index



oldrab          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word oldrab is a color that can be used for GUI elements.

It is a tuple! of value 72.72.16
Examples
view [
text 100x50 oldrab " "
]

vid-oldrab.png

top alphanumeric-index category-index



olive          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word olive is a color that can be used for GUI elements.

It is a tuple! of value 128.128.0
Examples
view [
text 100x50 olive " "
]

vid-olive.png

top alphanumeric-index category-index



on-alt-down          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-alt-up          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-aux-down          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-aux-up          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-change          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-click          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-close          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-create          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-dbl-click          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-detect          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-down          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-drag          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-drag-start          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-drop          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-enter          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-face-deep-change*          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-focus          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-key          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-key-down          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-key-up          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-menu          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-mid-down          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-mid-up          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-move          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-moving          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-over          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-pan          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-parse-event          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
To do by red-by-example team ...


top alphanumeric-index category-index



on-press-tap          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-resize          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-resizing          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-rotate          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-select          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-time          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-two-tap          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-unfocus          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-up          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-zoom          type:  GUI: VID, View!--    Cats: Events, GUI: VID, View
See 'Actors' in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



orange          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word orange is a color that can be used for GUI elements.

It is a tuple! of value 255.150.10
Examples
view [
text 100x50 orange " "
]

vid-orange.png

top alphanumeric-index category-index



origin          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



overlap?          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



pad          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



panel          type:  GUI: VID, View!--    Cats: GUI: VID, View
A panel is a container for other faces. We supply a block of faces.  
The default event is on-down

In VID, here is a black panel containing 2 buttons:

panel1: panel black [
panel1-b1: button "panel1-b1" [mytext/text: "panel1-b1 clicked" ]
panel1-b2: button "panel1-b2" [mytext/text: "panel1-b2 clicked" ]
]

There is a complete VID example in:

http://www.red-by-example.org/vid-choice-faces-red.html


There is an introduction to VID at:

http://www.red-by-example.org/vid.html


Its official View documentation is at:

https://doc.red-lang.org/en/view.html#_panel


top alphanumeric-index category-index



papaya          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word papaya is a color that can be used for GUI elements.

It is a tuple! of value 255.80.37
Examples
view [
text 100x50 papaya " "
]

vid-papaya.png

top alphanumeric-index category-index



para          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



pewter          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word pewter is a color that can be used for GUI elements.

It is a tuple! of value 170.170.170
Examples
view [
text 100x50 pewter " "
]

vid-pewter.png

top alphanumeric-index category-index



pink          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word pink is a color that can be used for GUI elements.

It is a tuple! of value 255.164.200
Examples
view [
text 100x50 pink " "
]

vid-pink.png

top alphanumeric-index category-index



progress          type:  GUI: VID, View!--    Cats: GUI: VID, View
This type represents a horizontal or vertical progress bar.

The default orientation is horizontal, because the default size for faces
is wider than its height. For a vertical slider, specify a size that is
taller than its width.

The optional value for the initial position can be a percent, or a float
between 0.0 and 1.0.

The default event is on-change

Its current value is available in 'data'.

There is a complete VID example in:

http://www.red-by-example.org/vid-misc-faces-red.html


There is an introduction to VID at:

http://www.red-by-example.org/vid.html


Its official View documentation is at:

https://doc.red-lang.org/en/view.html#_progress



top alphanumeric-index category-index



purple          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word purple is a color that can be used for GUI elements.

It is a tuple! of value 128.0.128
Examples
view [
text 100x50 purple " "
]

vid-purple.png

top alphanumeric-index category-index



radio          type:  GUI: VID, View!--    Cats: GUI: VID, View
A radio provides a radio-button, with an optional label.  Only one radio 
button per panel is allowed to be on.

The default event-handler is on-change, and the boolean state exists in
'data'.

Here is a VID example with 3 radios labelled "Big", "Small", "Medium".
Changing any of them results is the 3 states being printed.

panel2: panel orange [ ;-- orange panel, 3 radios
panel2-r1: radio "Big"
[print ["radios: " panel2-r1/data panel2-r2/data panel2-r3/data]]
panel2-r2: radio "Small"
[print ["radios: " panel2-r1/data panel2-r2/data panel2-r3/data]]
panel2-r3: radio "Medium"
[print ["radios: " panel2-r1/data panel2-r2/data panel2-r3/data]]
]


There is a complete VID example in:

http://www.red-by-example.org/vid-choice-faces-red.html


There is an introduction to VID at:

http://www.red-by-example.org/vid.html


Its official View documentation is at:

https://doc.red-lang.org/en/view.html#_radio


top alphanumeric-index category-index



rate          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



react          type:  GUI: VID, View!--    Cats: GUI: VID, View, Reactivity
See the official VID documents:
https://doc.red-lang.org/en/vid.html

top alphanumeric-index category-index



reblue          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word reblue is a color that can be used for GUI elements.

It is a tuple! of value 38.58.108
Examples
view [
text 100x50 reblue " "
]

vid-reblue.png

top alphanumeric-index category-index



rebolor          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word rebolor is a color that can be used for GUI elements.

It is a tuple! of value 142.128.110
Examples
view [
text 100x50 rebolor " "
]

vid-rebolor.png

top alphanumeric-index category-index



red          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect word red is a color that can be used for GUI elements.

It is a tuple! of value 255.0.0
Examples
view [
text 100x50 red " "
]

vid-red.png

top alphanumeric-index category-index



remove-event-func          type:  GUI: VID, View!--    Cats: GUI: VID, View
See the official View documents:
https://doc.red-lang.org/en/view.html

top alphanumeric-index category-index



remove-event-func          type:  GUI: VID, View!--    Cats: GUI: VID, View
See the official View documents:
https://doc.red-lang.org/en/view.html

top alphanumeric-index category-index



remove-reactor          type:  GUI: VID, View!--    Cats: GUI: VID, View
See the official View documents:
https://doc.red-lang.org/en/view.html

top alphanumeric-index category-index



request-dir          type:  GUI: VID, View!--    Cats: Directories, GUI: VID, View
Causes a dialog to appear asking the user to select a directory, and returns
the full directory path as a file! type, or a block of paths.
It returns none if no selection is made. The title bar shows:
'Browse For Folder'
It works in a Red GUI program, and also in a non-GUI console program.

There are no arguments.

Refinements
/title - to be displayed under the title bar. We provide a string!

/dir - Set starting directory. We provide a name, which can be a
string! or file!.

/filter - To Be Developed: Block of filters (filter-name filter):
a block!

/keep - Keep previous directory path

/multi - To Be Developed: Allows multiple file selection, returned as
a block.

Examples
; -------------------------------------------------------------------------
; Use request-dir from the Red console, on Windows
; -------------------------------------------------------------------------

red>> choice: request-dir
;user browsed to c:\mike\ALBUM\ Note the %, indicating a file!
red>> choice
== %/C/ALBUM/

; -------------------------------------------------------------------------
; /dir and /title refinements
; -------------------------------------------------------------------------

;add a title, and start with C:/mike selected
red>> print request-dir/title/dir "Choose Dir" "C:\mike"
== %/C/Mike/data/

top alphanumeric-index category-index



request-file          type:  GUI: VID, View!--    Cats: Files, GUI: VID, View
Causes a dialog to appear asking the user to select a file, and 
returns the full file path as a file! type, or block of paths.
It returns none if no selection is made. 'Open' is displayed
as the default title. It works in a Red GUI app, and also in a
non-GUI console app.

There are no arguments

Refinements
/title - window title. We supply a string!

/file - Default file name or directory. We supply a name as
a string! or file!.

/filter - supply a block of filters consisting of pairs of filter
names, and the actual filters.

/save - File save mode.

/multi - Allows multiple file selection, returned as a block.

Examples
; -------------------------------------------------------------------------
; request-file examples
; -------------------------------------------------------------------------

;display an 'open' dialog, on Windows
red>> choice: request-file
;note the file! type result
red>> choice
== %/C/red/try-demos.red

; -------------------------------------------------------------------------
; /filter refinement .jpg, .red
; -------------------------------------------------------------------------

red>> print request-file/filter ["jpegs" "*.jpg" "Red files" "*.red"]

top alphanumeric-index category-index



request-font          type:  GUI: VID, View!--    Cats: GUI: VID, View
Causes a dialog to appear asking the user to select a font, and returns
a font! object!, or none if no selection is made.
It works in a Red GUI program, and also in a non-GUI console program.

There are no arguments

Refinements

/mono - Show monospaced font only.

Examples
; -------------------------------------------------------------------------
; request-font examples
; -------------------------------------------------------------------------

;display the dialog. The Dayton font is selected by the user here
red>> choice: request-font

;note the result
red>> print choice
name: "Dayton"
size: 11
style: none
angle: 0
color: none
anti-alias?: false
shadow: none
state: none
parent: none

;and it is an object
red>> type? choice
== object!

top alphanumeric-index category-index



return          type:  GUI: VID, View!--    Cats: GUI: VID, View
The VID dialect word return is used to position the next GUI
elements from the left side of the window.
Examples
Red [
needs: 'view
]

view [
across
text "Line 1"
text "Line 2"
return
text "Line 3"
]

vid-return.png

top alphanumeric-index category-index



rich-text          type:  GUI: VID, View!--    Cats: GUI: VID, View
Rich-text is supported.  See:
https://github.com/red/red/wiki/Rich-Text-support

Examples
view
[ ;-- show a rich text face, with differing font size, colors
out-rich: rich-text 300x100 data [
i b "Hello" /b font 24 red " Red " /font blue "World!" /i
]
]

top alphanumeric-index category-index



right          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



rtd-layout          type:  GUI: VID, View!--    Cats: GUI: VID, View
USAGE:
RTD-LAYOUT spec

DESCRIPTION:
Returns a rich-text face from a RTD source code.
RTD-LAYOUT is a function! value.

ARGUMENTS:
spec [block!] "RTD source code."

REFINEMENTS:
/only => Returns only [text data] facets.
/with => Populate an existing face object.
face [object!] "Face object to populate."

RETURNS:
[object! block!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



screen          type:  GUI: VID, View!--    Cats: GUI: VID, View
Represents a graphic display unit connected to the computer (usually a 
monitor).

Its official View documentation is at:

https://doc.red-lang.org/en/view.html#_screen


top alphanumeric-index category-index



select          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



set-flag          type:  GUI: VID, View!--    Cats: GUI: VID, View
USAGE:
SET-FLAG face facet value

DESCRIPTION:
Sets a flag in a face object.
SET-FLAG is a function! value.

ARGUMENTS:
face [object!]
facet [word!]
value [any-type!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



set-focus          type:  GUI: VID, View!--    Cats: GUI: VID, View
USAGE:
SET-FOCUS face

DESCRIPTION:
Sets the focus on the argument face.
SET-FOCUS is a function! value.

ARGUMENTS:
face [object!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



show          type:  GUI: VID, View!--    Cats: GUI: VID, View
See the official View documents:
https://doc.red-lang.org/en/view.html

top alphanumeric-index category-index



sienna          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect provides named colors.  Each color has a tuple! value.  

For example, here we create a brown text element:

view [
text 100x50 brown " "
]


top alphanumeric-index category-index



silver          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect provides named colors.  Each color has a tuple! value.  

For example, here we create a brown text element:

view [
text 100x50 brown " "
]


top alphanumeric-index category-index



size-text          type:  GUI: VID, View!--    Cats: GUI: VID, View
In system/words, sometimes used in rich-text programming.

(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



sky          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect provides named colors.  Each color has a tuple! value.  

For example, here we create a brown text element:

view [
text 100x50 brown " "
]


top alphanumeric-index category-index



slider          type:  GUI: VID, View!--    Cats: GUI: VID, View
This type represents a cursor which can be moved along a horizontal or 
vertical axis. The optional value for the initial position can be a
percent, or a float between 0.0 and 1.0.

Its default event is: on-change

Its current value is available in 'data'.

The default orientation is horizontal, because the default size for
faces is wider than its height. For a vertical slider, specify a
size that is taller than its width.

Here is VID example where a slider's value is displayed in a text
and used to control a progress bar. Note the use of 'face' to
represent the current face. We could also have written 'slider1'.

slider1: slider 20x100 50% [ ;--vertical, initially at middle
mytext/text: face/data
progress1/data: face/data
]

There is a complete VID example in:
http://www.red-by-example.org/vid-misc-faces-red.html

There is an introduction to VID at:
http://www.red-by-example.org/vid.html

Its official View documentation is at:
https://doc.red-lang.org/en/view.html#_slider


top alphanumeric-index category-index



snow          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect provides named colors.  Each color has a tuple! value.  

For example, here we create a brown text element:

view [
text 100x50 brown " "
]


top alphanumeric-index category-index



space          type:  GUI: VID, View!--    Cats: GUI: VID, View
Changes the default spacing between faces.

Argument

a pair!

Examples
view [
size 300x200
title "Demo Window"
space 100x70 ;-- bigger horizontal/vertical spacing
b1: button "Hello"
b2: button "Goodbye"
return
]

top alphanumeric-index category-index



style          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



tab-panel          type:  GUI: VID, View!--    Cats: GUI: VID, View
A collection of panels, only one is visible at a time.  We supply a block 
of strings for the tabs.

The default event is: on-select.

Here is a VID example, with 3 tabs:

tab-panel 250x120 [
"Tab A" [h4 "In a tab!" button "Click in A" [print "A"] ]
"Tab B" [button "Click in B" [print "B"] ]
"Tab C" [button "Click in C" [print "C"] ]
]

There is a complete VID example in:

http://www.red-by-example.org/vid-misc-faces-red.html


There is an introduction to VID at:

http://www.red-by-example.org/vid.html


Its official View documentation is at:

https://doc.red-lang.org/en/view.html#_tab_panel



top alphanumeric-index category-index



tanned          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect provides named colors.  Each color has a tuple! value.  

For example, here we create a brown text element:

view [
text 100x50 brown " "
]


top alphanumeric-index category-index



teal          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect provides named colors.  Each color has a tuple! value.  

For example, here we create a brown text element:

view [
text 100x50 brown " "
]


top alphanumeric-index category-index



text          type:  GUI: VID, View!--    Cats: GUI: VID, View
This face is used to display text data on-screen.  The data can be 
changed later, e.g. by:

text-my-name/text: "Jimi"

There are also h1 h2 h3 h4 h5, which provide a
slightly shorter way of creating text with common font-sizes, as in:

h1: "Very big heading"
h5: "Small heading"

We cannot key-in data to a text - use the field for this.

Here is a VID example with a yellow text and a button. When we
click it, the text displays "Goodbye!":

view [
message: text yellow "Hello!" ;-- yellow, with initial string
button "Press Me" [message/text: "Goodbye!"] ;-- change it
]

There is a complete VID example in:

http://www.red-by-example.org/vid-text-faces-red.html


There is an introduction to VID at:

http://www.red-by-example.org/vid.html


Its official View documentation is at:

https://doc.red-lang.org/en/view.html#_text



top alphanumeric-index category-index



text-list          type:  GUI: VID, View!--    Cats: GUI: VID, View

This type represents a vertical list of text strings, displayed in a
fixed frame. A vertical scrollbar appears automatically if the content
does not fit the frame.

The drop-down, drop-list, and text-list are related.
The default event-handler is on-change

'selected' provides the position of the selection. This is -1 if no
selection exists.

In VID:

days-text-list1: text-list pink 90x110 data [
"Monday" "Tuesday" "Wednesday" "Thursday"
]

We can choose to preset an initial selection like this:

days-text-list: text-list pink 90x110 select 2 ;-- 2 refers to
"Tuesday"
data [
"Monday" "Tuesday" "Wednesday" "Thursday"
]

There is a complete VID example in:

http://www.red-by-example.org/vid-choice-faces-red.html


There is an introduction to VID at:

http://www.red-by-example.org/vid.html


Its official View documentation is at:

https://doc.red-lang.org/en/view.html#_text_list



top alphanumeric-index category-index



title          type:  GUI: VID, View!--    Cats: GUI: VID, View
Sets the container title.

Argument

A string!

Examples
view [
;-- set title for window
backdrop green
size 300x200
title "Demo Window" ;-- title of window
b1: button "Hello"
b2: button "Goodbye"
return
]

top alphanumeric-index category-index



top          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



transparent          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect provides named colors.  Each color has a tuple! value.  

For example, here we create a brown text element:

view [
text 100x50 brown " "
]


top alphanumeric-index category-index



underline          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



unview          type:  GUI: VID, View!--    Cats: GUI: VID, View
USAGE:
UNVIEW

DESCRIPTION:
Close last opened window view.
UNVIEW is a function! value.

REFINEMENTS:
/all => Close all views.
/only => Close a given view.
face [object!] "Window view to close."

(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



view          type:  GUI: VID, View!--    Cats: GUI: VID, View
The function view is used to:
- declare a GUI layout using VID
- invoke that GUI layout
Examples
Red [
needs: 'view
]

view [
below
text "Line 1"
text "Line 2"
]

top alphanumeric-index category-index



violet          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect provides named colors.  Each color has a tuple! value.  

For example, here we create a brown text element:

view [
text 100x50 brown " "
]


top alphanumeric-index category-index



water          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect provides named colors.  Each color has a tuple! value.  

For example, here we create a brown text element:

view [
text 100x50 brown " "
]


top alphanumeric-index category-index



wheat          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect provides named colors.  Each color has a tuple! value.  

For example, here we create a brown text element:

view [
text 100x50 brown " "
]


top alphanumeric-index category-index



white          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect provides named colors.  Each color has a tuple! value.  

For example, here we create a brown text element:

view [
text 100x50 brown " "
]


top alphanumeric-index category-index



window          type:  GUI: VID, View!--    Cats: GUI: VID, View
Represents a window displayed on the OS desktop. 

In VID the window is made large enough to hold all the faces, but we
can also choose our own fixed size.
The View Engine provides more facilities - such as handling a
window-resize event, and adding a menu bar.
In VID we can define a window like this:
view [
size 350x450 ;-- window size
title "Text faces" ;-- window title

t1: text "Hello" ;-- rest of VID code
;-- etc
]

Its official View documentation is at:

https://doc.red-lang.org/en/view.html#_window


top alphanumeric-index category-index



with          type:  GUI: VID, View!--    Cats: GUI: VID, View
Evaluates a block of Red code bound to the currently defined face. Allows
directly setting the face fields, overriding other VID options.

Note that the with is executed as the face is created. In the following,
if we reversed the order of b1 and b2, creating b2 first, an error would
result, because b1 does not exist (yet).


view [
b1: button "Hello" ;-- actually shows "HI!"
b2: button "Goodbye" with [b1/text: "HI!"]
]

top alphanumeric-index category-index



wrap          type:  GUI: VID, View!--    Cats: GUI: VID, View
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



yello          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect provides named colors.  Each color has a tuple! value.  

For example, here we create a brown text element:

view [
text 100x50 brown " "
]


top alphanumeric-index category-index



yellow          type:  GUI: VID, View!--    Cats: Colors, GUI: VID, View
The VID dialect provides named colors.  Each color has a tuple! value.  

For example, here we create a brown text element:

view [
text 100x50 brown " "
]


top alphanumeric-index category-index



copy          type:  Parse dialect!--    Cats: Parse dialect
Consult the Parse dialect page for information.

top alphanumeric-index category-index



skip          type:  Parse dialect!--    Cats: Parse dialect
Consult the Parse dialect page for information.

top alphanumeric-index category-index



box          type:  Draw Dialect!--    Cats: Draw Dialect
Consult the Draw pages for information.

top alphanumeric-index category-index



fill-pen          type:  Draw Dialect!--    Cats: Draw Dialect
Consult the Draw pages for information.

top alphanumeric-index category-index



line          type:  Draw Dialect!--    Cats: Draw Dialect
Consult the Draw pages for information.

top alphanumeric-index category-index



pen          type:  Draw Dialect!--    Cats: Draw Dialect
Consult the Draw pages for information.

top alphanumeric-index category-index



<          type:  op!--    Cats: Comparison
The infix word < loosely compares operands on its left and right side and
returns true if the operand on the left is smaller than the operand on the right.
Otherwise returns false.

Has 2 operands of any datatype!.

Loose comparison means that:
- the case of strings is ignored when comparing
- same numeric values for different datatypes are considered equal
Examples
2 < 3
== true

2 < 2.0
== false

22-03-2000 < 14-04-2012
== true

"ABC" < "abc"
== false

"abc" < "ABC"
== false

"abc" = "ABC"
== true

top alphanumeric-index category-index



<<          type:  op!--    Cats: Bit manipulation
The word << shifts its first argument (an integer!) to the left
by the number of bits in its second argument (also an integer!).

The sign is taken into account.
Examples
red>> to-hex 6
== #00000006

red>> to-hex 6 << 1
== #0000000C

red>> to-hex 6 << 2
== #00000018

red>> to-hex 6 << 3
== #00000030

red>> to-hex 6 << 4
== #00000060

red>> to-hex -6
== #FFFFFFFA

red>> to-hex -6 << 1
== #FFFFFFF4

red>> to-hex -6 << 2
== #FFFFFFE8

red>> to-hex -6 << 3
== #FFFFFFD0

red>> to-hex -6 << 4
== #FFFFFFA0

top alphanumeric-index category-index



<=          type:  op!--    Cats: Comparison
The infix word <= loosely compares operands on its left and right side and
returns true if the operand on the left is smaller than or equal to the operand
on the right. Otherwise returns false.

Has 2 operands of any datatype!.

Loose comparison means that:
- the case of strings is ignored when comparing
- same numeric values for different datatypes are considered equal
Examples
2 <= 3
== true

2 <= 2.0
== true

22-03-2000 <= 14-04-2012
== true

"ABC" <= "abc"
== true

"abc" <= "ABC"
== true

top alphanumeric-index category-index



<>          type:  op!--    Cats: Comparison
The infix word <> compares 2 values, and returns true if they are
NOT equal, otherwise false.

The 2 values need not be of the same datatype!.
It is equivalent to the not-equal? function.

Note that string! values which only differ in case are considered equal.

Red also has a strict-equal? function, where the types must be the same,
and string! case is checked.
Examples
red>> a: 33
== 33

red>> a <> 35
== true

red>> b: [1 2 3]
== [1 2 3]

red>> b <> [1 2 3]
== false

red>> 12 <> 12.0
== false

red>> "abc" <> "abc"
== false

red>> "abC" <> "ABC"
== false
; Note uppercase considered equal to lowercase!

top alphanumeric-index category-index



=          type:  op!--    Cats: Comparison
The infix word = loosely compares operands on its left and right side and
returns true if the operand on the left is loosely equal to the operand on the
right. Otherwise returns false.

Has 2 operands of any datatype!.

Loose comparison means that:
- the case of strings is ignored when comparing
- same numeric values for different datatypes are considered equal
Examples
2 = 3
== false

2 = 2.0
== true

22-03-2000 = 14-04-2012
== false

"ABC" = "abc"
== true

top alphanumeric-index category-index



==          type:  op!--    Cats: Comparison
The infix word == strictly compares operands on its left and right side and
returns true if the operand on the left is strictly equal to the operand on the
right. Otherwise returns false.

Has 2 operands of any datatype!.

The comparison is "strict", which means that:
- numeric operands are not equal if they have a different datatype
- string operands are not equal if their case differs
Examples
2 == 3
== false

2 == 2.0
== false

22-03-2000 == 14-04-2012
== false

"ABC" == "abc"
== false

top alphanumeric-index category-index



=?          type:  op!--    Cats: Comparison
The infix word =? returns true if two values have the same identity.

As regards series! (including string!s) the references (pointers) to
the series! are compared.
Examples
red>> a: 22
== 22

red>> b: 22
== 22

red>> a =? b
== true

red>> c: [1 2 3]
== [1 2 3]

red>> d: c
== [1 2 3]

red>> c =? d
== true
; Pointers are compared - they indeed reference the same series

red>> c: [3 2 1]
== [3 2 1]

red>> d: [3 2 1]
== [3 2 1]

red>> c = d
== true
; Values are compared - are equal

red>> c =? d
== false
; Pointers are compared - not referencing the same series

top alphanumeric-index category-index



>          type:  op!--    Cats: Comparison
The infix word > loosely compares operands on its left and right side
returns true if the operand on the left is greater than the operand on
the right. Otherwise returns false.

Has 2 operands of any datatype

Loose comparison means that:
- the case of strings is ignored when comparing
- same numeric values for different datatypes are considered equal
Examples
Examples

2 > 3
== false

2 > 2.0
== false

22-03-2000 > 14-04-2012
== false

"ABC" > "abc"
== false

"abc" > "ABC"
== false

"abc" = "ABC"
== true

top alphanumeric-index category-index



>=          type:  op!--    Cats: Comparison
The infix word >= loosely compares operands on its left and right side and
returns true if the operand on the left is greater than or equal to the operand
on the right. Otherwise returns false.

Has 2 operands of any datatype!.

Loose comparison means that:
- the case of strings is ignored when comparing
- same numeric values for different datatypes are considered equal
Examples
2 >= 3
== false

2 >= 2.0
== true

22-03-2000 >= 14-04-2012
== false

"ABC" >= "abc"
== true

"abc" >= "ABC"
== true

top alphanumeric-index category-index



>>          type:  op!--    Cats: Bit manipulation
The word >> shifts its first argument (an integer!) to the right
by the number of bits in its second argument (also an integer!).

The sign is taken into account.
Examples
red>> to-hex 6
== #00000006

red>> to-hex 6 >> 1
== #00000003

red>> to-hex 6 >> 2
== #00000001

red>> to-hex 6 >> 3
== #00000000

red>> to-hex 6 >> 4
== #00000000

red>> to-hex -6
== #FFFFFFFA

red>> to-hex -6 >> 1
== #FFFFFFFD

red>> to-hex -6 >> 2
== #FFFFFFFE

red>> to-hex -6 >> 3
== #FFFFFFFF

red>> to-hex -6 >> 4
== #FFFFFFFF

top alphanumeric-index category-index



>>>          type:  op!--    Cats: Bit manipulation
The word >>> shifts its first argument (an integer!) to the right
by the number of bits in its second argument (also an integer!).

This is a shift which ignores the sign.
Examples
red>> to-hex 6
== #00000006

red>> to-hex 6 >>> 1
== #00000003

red>> to-hex 6 >>> 2
== #00000001

red>> to-hex 6 >>> 3
== #00000000

red>> to-hex 6 >>> 4
== #00000000

red>> to-hex -6
== #FFFFFFFA

red>> to-hex -6 >>> 1
== #7FFFFFFD

red>> to-hex -6 >>> 2
== #3FFFFFFE

red>> to-hex -6 >>> 3
== #1FFFFFFF

red>> to-hex -6 >>> 4
== #0FFFFFFF

top alphanumeric-index category-index



?          type:  function!--    
This word is a synonym for help
top alphanumeric-index category-index


??          type:  function!--    Cats: Documentation, Help & Debug
The word ?? prints a Red word! (given as its argument)
and the value it refers to, in a molded format. This means that
the output includes type information (e.g. [ ], " ").

It is very useful for debugging.

Warning: when used with a function! name, it displays the
function! specification, rather than evaluating
that function!.
Examples
red>> age: 35
== 35

red>> ?? age
age: 35
== 35

red>> older: 1 + ?? age
age: 35
== 36

red>> ?? 44
*** Script error: ?? does not allow integer for its value argument
*** Where: ??

red>> ?? sin 0.4
sin: routine ["Returns the trigonometric sine" angle [float!]
"Angle in radians"][natives/sine* no 1]
== 0.4
; Effectively the 0.4 here is a stand-alone value;
; ?? does not do anything with it!

top alphanumeric-index category-index



a-an          type:  function!--    Cats: String manipulation
USAGE:
A-AN str

DESCRIPTION:
Returns the appropriate variant of a or an (simple, vs 100% grammatically correct).
A-AN is a function! value.

ARGUMENTS:
str [string!]

REFINEMENTS:
/pre => Prepend to str.

; -------------------------------------------------------------------------
; a-an
; -------------------------------------------------------------------------

>> a-an "apple"
== "an"
>> a-an "chair"
== "a"

top alphanumeric-index category-index



about          type:  function!--    Cats: Help & Debug
Displays the version of Red currently in use

Has no parameters
Examples
about
Red 0.5.4 - 1-Dec-2015/11:46:16+1:00

top alphanumeric-index category-index



absolute          type:  action!--    Cats: Math
The absolute word evaluates an expression or a value 
and returns the absolute value if the datatype is appropriate.

Has 1 parameter, an expression or a value
Examples
absolute 1 - 3
== 2
; 1 - 3 == -2
; Returns the absolute value of -2, which is 2

absolute -2 / 5
== 0.4
; -2 / 5 == -0.4
; Returns the absolute value of -0.4, which is 0.4

absolute 6 / 3
== 2
; 6 / 3 == 2
; Returns the absolute value of 2, which is 2

absolute -2x5
== 2x5

top alphanumeric-index category-index



acos          type:  function!--    
This word is a synonym for arccosine
top alphanumeric-index category-index


action!          type:  datatype!--    Cats: Datatypes
The datatype! action! encompassess a specific set of native!
functions.
Examples
; -------------------------------------------------------------------------
; List all functionss that are an action
; -------------------------------------------------------------------------

red>> ? action!
absolute => Returns the non-negative value
add => Returns the sum of the two values
and~ => Returns the first value ANDed with the second
append => Inserts value(s) at series tail; returns series head
at => Returns a series at a given index
back => Returns a series at the previous index
change => Changes a value in a series and returns the series after
the change.
clear => Removes series values from current index to tail; returns
new tail
complement => Returns the opposite (complementing) value of the input `
value
copy => Returns a copy of a non-scalar value
divide => Returns the quotient of two values
even? => Returns true if the number is evenly divisible by 2
find => Returns the series where a value is found, or NONE
form => Returns a user-friendly string representation of a value
head => Returns a series at its first index
head? => Returns true if a series is at its first index
index? => Returns the current index of series relative to the head,
or of word in a context
insert => Inserts value(s) at series index; returns series past the
insertion
length? => Returns the number of values in the series, from the current
index to the tail
make => Returns a new value made from a spec for that value's type
modify => Change mode for target aggregate value
mold => Returns a source format string representation of a value
move => Moves one or more elements from one series to another
position or series
multiply => Returns the product of two values
negate => Returns the opposite (additive inverse) value
next => Returns a series at the next index
odd? => Returns true if the number has a remainder of 1 when divided
by 2
or~ => Returns the first value ORed with the second
pick => Returns the series value at a given index
poke => Replaces the series value at a given index, and returns
the new value
power => Returns a number raised to a given power (exponent)
put => Replaces the value following a key, and returns the new value
random => Returns a random value of the same datatype; or shuffles series
read => Read from a file, URL, or other port
reflect => Returns internal details about a value via reflection
remainder => Returns what is left over when one value is divided by another
remove => Returns the series at the same index after removing a value
reverse => Reverses the order of elements; returns at same position
round => Returns the nearest integer. Halves round up (away from zero)
by default
select => Find a value in a series and return the next value, or NONE
skip => Returns the series relative to the current index
sort => Sorts a series (modified); default sort order is ascending
subtract => Returns the difference between two values
swap => Swaps elements between two series or the same series
tail => Returns a series at the index after its last value
tail? => Returns true if a series is past its last value
take => Removes and returns one or more elements
to => Converts to a specified datatype
trim => Removes space from a string or NONE from a block or object
write => Writes to a file, URL, or other port
xor~ => Returns the first value exclusive ORed with the second

; -------------------------------------------------------------------------
; Check if a word is an action!
; -------------------------------------------------------------------------

red>> action? :take ; Colon is mandatory to get to function definition
== true

top alphanumeric-index category-index



action?          type:  function!--    Cats: Type Checking
The word action? returns true if its argument is an action!
type, or false otherwise.
Examples
red>> action? :take     ; Colon is mandatory to get to function definition
== true

top alphanumeric-index category-index



add          type:  action!--    Cats: Math
The word add adds 2 values together.
This is equivalent to the infix operator +.

Has 2 operands, which can be expressions or values
Examples
; -------------------------------------------------------------------------
; Add some number!s
; -------------------------------------------------------------------------


add -1 3
== 2

add 4 / 2 5
== 7
; 4 / 2 == 2
; 2 + 5 == 7
; Returns 7

add 2.3 7.77 - 2
== 8.07
; 7.77 - 2 == 5,77
; 2.3 + 5.77 == 8.07
; Returns 8.07

; -------------------------------------------------------------------------
; Add a number! to a pair! and vv
; -------------------------------------------------------------------------


red>> add 2x4 5
== 7x9

red>> add 5 2x4
== 7x9


top alphanumeric-index category-index



alert          type:  function!--    Cats: Input
docstart
USAGE:
ALERT msg

DESCRIPTION:
ALERT is a function! value.

ARGUMENTS:
msg [string! block!]
.docend

Displays a pop-up notification box, with a message and an OK button.

The program waits, and continues when OK is clicked, or the 'enter' key is pressed.

Examples

alert "Hello"
alert ["Year is " 2022]


top alphanumeric-index category-index



all          type:  native!--    Cats: Boolean, Comparison, Logic
The word all evaluates each expression in a block in turn 
and either returns the last resulting value (if that value is
not falsey) or returns none if it encounters a falsey
resulting value.

Has 1 parameter, a block.

The resulting value of all can be used in the if or either words, where all
functions like a short-circuit and.
Examples
all [1 + 1 2 + 2 3 = 3 2 + 6]
== 8
; 1 + 1 == 2 (not falsey, so evaluation continues)
; 2 + 2 == 4 (not falsey, so evaluation continues)
; 3 = 3 == true (not falsey, so evaluation continues)
; 2 + 6 == 8
; Returns the last resulting value (8) because no falsey values detected

all [1 + 1 3 = 4 2 + 2 "John"]
== none
; 1 + 1 == 2 (which is not falsey, so evaluation continues)
; 3 = 4 == false
; Returns none immediately, because a falsey value (false) is detected

top alphanumeric-index category-index



all-word!          type:  typeset!--    Cats: Datatypes
all-word! is a typeset! value: 
make typeset! [word! set-word! lit-word! get-word! refinement! issue!]

top alphanumeric-index category-index



all-word?          type:  function!--    Cats: Type Checking
all-word? returns true if its argument is any all-word! type.

It has no refinements.

Examples
; -------------------------------------------------------------------------
; Try block, word, and /refinement
; -------------------------------------------------------------------------

>> all-word? [1 2]
== false
>> all-word? 'find
== true
>> all-word? first [find]
== true
>> all-word? /ref
== true

top alphanumeric-index category-index



also          type:  function!--    Cats: Evaluation, Special Purpose
The word also first evaluates its first argument and then
also evaluates its second argument.
Examples
red>> a: 4
== 4

red>> b: 5
== 5

red>> also c: a + b c: c * a
== 9 ; Returns result of first expression

red>> c
== 36 ; Contains result of last expression

top alphanumeric-index category-index



alter          type:  function!--    Cats: Series, String manipulation
The word alter appends/removes a value to/from a series!.
The value can be of any type.

If the value does NOT exist in the series! it is appended, and true is returned.
The original series! is modified.

If the value does exist, it is removed, and false is returned.

Note that find can be used to search a value in a series!.

There are no refinements.
Examples
red>> a: ["cat" "dog"]
== ["cat" "dog"]

red>> alter a "fish"
== true

red>> a
== ["cat" "dog" "fish"]

red>> alter a "fish"
== false

red>> a
== ["cat" "dog"]

red>> find a "dog"
== ["dog"]

red>> find a "fish"
== none

top alphanumeric-index category-index



and          type:  op!--    Cats: Bit manipulation, Boolean, Comparison, Logic
The infix word and performs a logical "and" of two values.
The values are restricted to these types:
logic! integer! char! bitset! typeset! pair! tuple! vector!

It is the infix version of the and~ word.

In the case of anding two integer!s (or types closely related to integer!s,
such as char!, pair!), a bitwise (bit-by-bit) process is performed.

In general, types can be mixed, but logic! types cannot be mixed with other types.

The type of the result is the same type as the first value for a bitwise and.
For a logic and true or false are returned.

There are no refinements.
Examples
; -------------------------------------------------------------------------
; And some number!s
; -------------------------------------------------------------------------


red>> (3 > 2) and true
== true

red>> 8 and 16
== 0
red>> 16 and false
*** Script error: logic type is not allowed here
*** Where: and

; -------------------------------------------------------------------------
; And pair!s
; -------------------------------------------------------------------------


red>> my-pair: 3x4
== 3x4

red>> my-pair and 1
== 1x0

red>> 1 and my-pair
*** Script error: and does not allow pair for its value2 argument
*** Where: and

; -------------------------------------------------------------------------
; And vector!s
; -------------------------------------------------------------------------


red>> v1: make vector! [1 2 3]
== make vector! [1 2 3]

red>> v2: make vector! [1 1 1]
== make vector! [1 1 1]

red>> v1 and v2
== make vector! [1 0 1]

top alphanumeric-index category-index



and~          type:  action!--    Cats: Bit manipulation, Boolean, Comparison, Logic
The and~ word performs a logical "and" of its 2 arguments.
The arguments are restricted to these types:
logic! integer! char! bitset! typeset! pair! tuple! vector!

It is the functional version of the infix and word.

In the case of and~ing two integer!s (or types closely related to integer!s,
such as char!, pair!), a bitwise (bit-by-bit) process is performed.

In general, types can be mixed, but logic! types cannot be mixed with other types.

The type of the result is the same type as the first value for a bitwise and~.
For a logic and~ true or false are returned.

There are no refinements.
Examples
; -------------------------------------------------------------------------
; Using number!s
; -------------------------------------------------------------------------


red>> and~ (3 > 2 ) true
== true

red>> and~ 8 16
== 0

; -------------------------------------------------------------------------
; Using bad parameter
; -------------------------------------------------------------------------


red>> and~ 16 false
*** Script error: logic type is not allowed here
*** Where: and~

; -------------------------------------------------------------------------
; Using pair!
; -------------------------------------------------------------------------


red>> my-pair: 3x4
== 3x4

red>> and~ my-pair 1
== 1x0

red>> and~ 1 my-pair
*** Script error: and~ does not allow pair for its value2 argument
*** Where: and~

; -------------------------------------------------------------------------
; Using vector!
; -------------------------------------------------------------------------


red>> v1: make vector![1 2 3]
== make vector! [1 2 3]

red>> v2: make vector![1 1 1]
== make vector! [1 1 1]

red>> and~ v1 v2
== make vector! [1 0 1]

top alphanumeric-index category-index



any          type:  native!--    Cats: Boolean, Comparison, Logic
The word any evaluates each expression in a block! in turn and returns
the first resulting value that is not falsey.

If all resulting values are falsey it returns none.

Has 1 parameter, a block!

The resulting value of any can be used in the if or either words,
where any functions like a short-circuit or.
Examples
any [none false 1 false]
== 1
; none -> none (is falsey, so evaluation continues)
; false -> false (is falsey, so evaluation continues)
; 1 == 1
; Returns 1 immediately because a non falsey value (1) is detected

any [2 = 3 4 = 5 2 + 2 = 4 5 - 3 = 1]
== true
; 2 = 3 == false (is falsey, so evaluation continues)
; 4 = 5 == false (is falsey, so evaluation continues)
; 2 + 2 = 4 == true
; Returns true immediately because a non falsey value (true) is detected

top alphanumeric-index category-index



any-block!          type:  typeset!--    Cats: Datatypes
ANY-BLOCK! is a typeset! value: make typeset! [block! paren! path! lit-path!
set-path! get-path! hash!]



top alphanumeric-index category-index



any-block?          type:  function!--    Cats: Type Checking
USAGE:
ANY-BLOCK? value

DESCRIPTION:
Returns true if the value is any type of any-block.
ANY-BLOCK? is a function! value.

ARGUMENTS:
value [any-type!]

; -------------------------------------------------------------------------
; any-block? Examples
; -------------------------------------------------------------------------

>> any-block? [1 2]
== true
>> any-block? "234"
== false
>> any-block? first [ (1 2 3)]
== true

top alphanumeric-index category-index



any-function!          type:  typeset!--    Cats: Datatypes
ANY-FUNCTION! is a typeset! value: make typeset! [native! action! op! function! routine!]

top alphanumeric-index category-index



any-function?          type:  function!--    Cats: Type Checking
The word any-function? returns true if its argument is a any-function!.

It has no refinements.
Examples
red>> any-function? a
== false

red>> any-function? :find
== true
; The colon (:) gets the definition, not the value of a function

top alphanumeric-index category-index



any-list!          type:  typeset!--    Cats: Datatypes
The word any-list! is a typeset! of value: [block! paren! hash!].

We can test if any item is an any-list! with the any-list? function
Examples
red>> any-list!
== make typeset! [block! paren! hash!]

red>> a: [1 2 3]
== [1 2 3]

red>> any-list? a
== true

red>> any-list? 3
== false

top alphanumeric-index category-index



any-list?          type:  function!--    Cats: Type Checking
The word any-list? returns true if its argument is an any-list! type, 
otherwise false.

An any-list! is a typeset! of:
block! paren! hash!

Its argument can be of any type.
Examples
; -------------------------------------------------------------------------
; try some types with any-list?
; -------------------------------------------------------------------------

red>> any-list? "text"
false

red>> any-list? 127.33.63
== false

red>> any-list? [22 33]
== true

red>> any-list? (2 3)
== false

red>> any-list? (2 3) ; invalid - Red tries to evaluate the argument
== false

red>> first [(2 3)] ; valid - [ ] prevents evaluation
== (2 3)

red>> any-list? first [(2 3)] ; now it works!
== true

top alphanumeric-index category-index



any-object!          type:  typeset!--    Cats: Datatypes
A typeset!
make typeset! [object! error!]

See any-object?


top alphanumeric-index category-index



any-object?          type:  function!--    Cats: Type Checking
The word any-object? returns true if its argument is an object!.

It has no refinements.
Examples
red>> my-obj: make object! [ x: 10 y: 10 ]
== make object! [
x: 10
y: 10
]

red>> any-object? my-obj
== true

red>> a: 22

red>> any-object? a
== false

top alphanumeric-index category-index



any-path!          type:  typeset!--    Cats: Datatypes
Is a typeset!
make typeset! [path! lit-path! set-path! get-path!]

See any-path?

top alphanumeric-index category-index



any-path?          type:  function!--    Cats: Type Checking
The word any-path? returns true if its argument is a valid path! variant.
Otherwise false.

In Red, there are several types of path! like:
path! lit-path! set-path! get-path!

For more details on the ways of interpreting a word (involving ' and :),
the reader should look at the lit-word!, get-word! and set-word! docs.
Examples
; -------------------------------------------------------------------------
; Standard paths. Note: we use a [block] to prevent evaluation
; -------------------------------------------------------------------------

red>> any-path? first [a/b/c]
== true

red>> path? first [a/b/c]
== true

red>> type? first [a/b/c]
== path!

red>> any-path? first [a / b] ; Surprise - it is a division!
== false

; -------------------------------------------------------------------------
; Set paths.
; -------------------------------------------------------------------------

red>> any-path? first[a/b:]
== true

red>> set-path? first[a/b:]
== true

red>> type? first[a/b:]
== set-path!

red>> type? first[a:/b/c] ; Surprise - because of colon in 2nd position!
== url!

red>> any-path? first [a:/b/c]
== false

; -------------------------------------------------------------------------
; Get paths.
; -------------------------------------------------------------------------

red>> any-path? first [:a/b/c]
== true

red>> get-path? first [:a/b/c]
== true

red>> type? first [:a/b/c]
== get-path!

; -------------------------------------------------------------------------
; Lit paths.
; -------------------------------------------------------------------------

red>> any-path? first ['a/b/c]
== true

red>> lit-path? first ['a/b/c]
== true

red>> type? first ['a/b/c]
== lit-path!

top alphanumeric-index category-index



any-string!          type:  typeset!--    Cats: Datatypes
Is a typeset! 
make typeset! [string! file! url! tag! email!]

See any-string?

top alphanumeric-index category-index



any-string?          type:  function!--    Cats: Type Checking
The word any-string? returns true if its argument is any type of string!,
including the types string!, file! and url!.

It has no refinements.
Examples
red>> any-string? http://www.aaa.com
== true

red>> any-string? "fred"
== true

red>> any-string? 123
== false

red>> any-string? %notes/data.txt
== true

top alphanumeric-index category-index



any-type!          type:  typeset!--    Cats: Datatypes

top alphanumeric-index category-index



any-word!          type:  typeset!--    Cats: Datatypes
any-word! is a typeset! value:

make typeset! [word! set-word! lit-word! get-word!]

top alphanumeric-index category-index



any-word?          type:  function!--    Cats: Type Checking
The word any-word? returns true if its argument can be any-word!.

It has no refinements.
Examples
red>> any-word? 123
== false
; 123 is a number, not a symbol

red>> any-word? find
*** Script error: find is missing its series argument
*** Where: find
; Red tries to invoke the function find but fails on missing arguments

red>> any-word? 'find
== true
; Red takes quoted symbols literally

red>> any-word? :find
== false
; A function definition is not a word

red>> a: 'find
== find

red>> any-word? a
== true

top alphanumeric-index category-index



append          type:  action!--    Cats: Series, String manipulation
The word append inserts value(s) at the end of a series! 
and returns the head of the series. The original series is changed.

Arguments:
1. the series to be extended can be any series a bitmap! or a map!
2. the value to be appended can be any-type!

Refinements
/part - limit the number of values inserted. (a number! or a series index)
/only - insert block types as single values (overrides /part).
/dup - duplicate the inserted values. Provide a number!
Examples
; -------------------------------------------------------------------------
; Append to a block!
; -------------------------------------------------------------------------

red>> a-block: [1 2 3 "four" 5]
== [1 2 3 "four" 5]

red>> append a-block 6
== [1 2 3 "four" 5 6]

red>> append a-block [7 8 "nine" [10 11]]
== [1 2 3 "four" 5 6 7 8 "nine" [10 11]]

; -------------------------------------------------------------------------
; Append to a string!
; -------------------------------------------------------------------------

red>> a-string: "ABCD"
== "ABCD"

red>> append a-string "123"
== "ABCD123"

red>> append a-string [6 5 4]
== "ABCD123654" ; see what happens here?

; -------------------------------------------------------------------------
; /part refinement
; -------------------------------------------------------------------------

red>> series-1: [1 2 3 4 5 6]
== [1 2 3 4 5 6]

red>> series-2: [100 200 300 400 500]
== [100 200 300 400 500]

red>> append/part series-1 series-2 3
== [1 2 3 4 5 6 100 200 300] ; only 3 items appended

; -------------------------------------------------------------------------
; /only refinement
; -------------------------------------------------------------------------

red>> series-1: [1 2 3 4 5 6]
== [1 2 3 4 5 6]

red>> series-2: [100 200 300 400 500]
== [100 200 300 400 500]

red>> append/only series-1 series-2
== [1 2 3 4 5 6 [100 200 300 400 500]] ; appended as a comnplete block

; -------------------------------------------------------------------------
; /dup refinement - note duplicated values at end
; -------------------------------------------------------------------------

red>> series-1: [1 2 3 4 5 6]
== [1 2 3 4 5 6]

red>> series-2: [100 200]
== [100 200]

red>> append/dup series-1 series-2 3
== [1 2 3 4 5 6 100 200 100 200 100 200]

top alphanumeric-index category-index



arccosine          type:  native!--    Cats: Math
The word arccosine returns the trigonometric arccosine (in degrees by default).

Has 1 parameter, a number!.

Refinements:
/radians : returns the angle in radians;
without refinement returns the angle in degrees.

The resulting numeric angle value of arccosine can be used in an expression.
Examples
arccosine 0.5
== 60.0

arccosine/radians 1
== 0.0

top alphanumeric-index category-index



arcsine          type:  native!--    Cats: Math
The word arcsine returns the trigonometric arcsine (in degrees by default).

Has 1 parameter, a number!.

Refinements:
/radians : returns the angle in radians;
without refinement returns the angle in degrees.
Examples
arcsine 0.5
== 30.0

arcsine/radians 0
== 0.0

top alphanumeric-index category-index



arctangent          type:  native!--    Cats: Math
The word arctangent returns the trigonometric arctangent (in degrees by default).

Has 1 parameter, a number!.

Refinements:
/radians : returns the angle in radians;
without refinement returns the angle in degrees.
Examples
arctangent 0
== 0.0

arctangent/radians 0
== 0.0

top alphanumeric-index category-index



arctangent2          type:  native!--    Cats: Math
USAGE:
ARCTANGENT2 y x

DESCRIPTION:
Returns the smallest angle between the X axis and the point (x,y) (-pi to pi).
ARCTANGENT2 is a native! value.

ARGUMENTS:
y [number!]
x [number!]

RETURNS:
[float!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



as          type:  native!--    Cats: Conversion
USAGE:
AS type spec

DESCRIPTION:
Coerce a series into a compatible datatype without copying it.
AS is a native! value.

ARGUMENTS:
type [datatype! block! paren! any-path! any-string!] "The datatype
or example value."
spec [block! paren! any-path! any-string!] "The series to coerce."


; -------------------------------------------------------------------------
; as examples
; -------------------------------------------------------------------------

>> b: [1 2 3]
== [1 2 3]
>> p: as paren! b
== (1 2 3)
>> b
== [1 2 3] ;-- nb unchanged


top alphanumeric-index category-index



as-color          type:  routine!--    Cats: Casting Types, Conversion, Colors
The word as-color generates a tuple! with R, G and B values
from its 3 integer! arguments.
Examples
red>> as-color 255 0 0
== 255.0.0

; -------------------------------------------------------------------------
; Predefined colors (e.g. red green etc.) are available also
; -------------------------------------------------------------------------

red>> red
== 255.0.0

red>> green
== 0.255.0

red>> yellow
== 255.255.0

top alphanumeric-index category-index



as-ipv4          type:  routine!--    Cats: Casting Types, Conversion, URL/Internet
The word as-ipv4 returns an IP version 4 address created from
its 4 integer! arguments.

If an argument is not within the range 0 .. 255, Red tries to
"guess" an appropriate value using the modulo of its (absolute) value.
Examples
red>> as-ipv4 1 3 12 253
== 1.3.12.253

red>> as-ipv4 1 3 12 0
== 1.3.12.0

red>> as-ipv4 1 3 12 255
== 1.3.12.255

red>> as-ipv4 1 3 12 256
== 1.3.12.0

red>> as-ipv4 1 3 12 257
== 1.3.12.1

red>> as-ipv4 1 3 12 258
== 1.3.12.2

red>> as-ipv4 0 3 12 255
== 0.3.12.255

red>> as-ipv4 -1 3 12 255
== 255.255.255.255

red>> as-ipv4 -2 3 12 255
== 254.255.255.255

red>> as-ipv4 -3 3 12 255
== 253.255.255.255

top alphanumeric-index category-index



as-pair          type:  native!--    Cats: Casting Types, Conversion
The word as-pair combines 2 integer! or float! values into a pair!.
Examples
; -------------------------------------------------------------------------
; Demonstrate mixed integers and floats, also truncation
; -------------------------------------------------------------------------

red>> as-pair 22 33
22x33

red>> as-pair 22 33.9
22x33

red>> as-pair 44.3 44.99
44x44

top alphanumeric-index category-index



as-rgba          type:  routine!--    Cats: Casting Types, Conversion, Colors
USAGE:
AS-RGBA a b c d

DESCRIPTION:
Combine a, b, c and d values into a tuple.
AS-RGBA is a routine! value.

ARGUMENTS:
a [integer!]
b [integer!]
c [integer!]
d [integer!]

; -------------------------------------------------------------------------
; as-rgba
; -------------------------------------------------------------------------

>> as-rgba 255 0 255 1
== 255.0.255.1

top alphanumeric-index category-index



asin          type:  function!--    
This word is a synonym for arcsine
top alphanumeric-index category-index


ask          type:  function!--    Cats: Input
Displays a prompt and gets the value that the user types at STDIN.

Has 1 parameter, a string!

The resulting string value of ask can be used in an expression
Examples
answer: ask "What is your name?"
What is your name?Carl
== "Carl"

answer
== "Carl"

top alphanumeric-index category-index



at          type:  action!--    Cats: Series, String manipulation
The at word returns a series! at a given integer index.

Note that it does not extract one item. Rather, it returns a reference (pointer)
into the original series!.

The original series! is unchanged.

Note that series! (which includes string!s) are indexed from 1.

If the index is off the 'left-hand side' of the series!, the whole series!
is returned.

If the series! is beyond the right-hand side, an empty series! is returned.

There are no refinements.
Examples
red>> at [1 2 3 4 5] 3
== [3 4 5]

red>> at "abcde" 3
== "cde"

red>> at "abcd" 6
== ""

red>> at [1 2 3 4] -2
== [1 2 3 4]

red>> at [1 2 3 4] 0
== [1 2 3 4]

top alphanumeric-index category-index



atan          type:  function!--    
This word is a synonym for arctangent
top alphanumeric-index category-index


atan2          type:  function!--    
This word is a synonym for arctangent2
top alphanumeric-index category-index


attempt          type:  function!--    Cats: Error
The word attempt tries to evaluate a block! 
and returns the result or none if an error occurs.

The effect of attempt is similar to that of error? try[block].
If you need more details about specific errors, look at try,
cause-error error?, and the error! type.

Examples
red>> s: "abcd"
== "abcd"
red>> calc: 3 * s
*** Script error: * does not allow string for its value2 argument
*** Where: *

red>> calc: attempt [3 * s]
== none
red>> calc
== none

red>> calc: attempt [3 * 2.2]
== 6.6
red>> calc
== 6.6

top alphanumeric-index category-index



average          type:  function!--    Cats: Math
USAGE:
AVERAGE block

DESCRIPTION:
Returns the average of all values in a block.
AVERAGE is a function! value.

ARGUMENTS:
block [block! vector! paren! hash!]

; -------------------------------------------------------------------------
; avergag
; -------------------------------------------------------------------------

>> average [7 8]
== 7.5
>> type? average [6 8] ;-- note type of result
== float!

top alphanumeric-index category-index



back          type:  action!--    Cats: Series, String manipulation
The word back moves the index of a series! 1 position towards
the head (= the start) of the series!.

When a series! index is already at head position, back won't
change the index; it stays at head.

The opposite of back is next.
Examples
red>> ser: [1 2 3]
== [1 2 3]

red>> head? ser
== true

red>> index? ser
== 1

red>> back ser
== [1 2 3]

red>> ser: back ser
== [1 2 3]

red>> head? ser
== true

red>> index? ser
== 1

red>> ser: tail ser
== []

red>> index? ser
== 4

red>> ser: back ser
== [3]

red>> index? ser
== 3

red>> ser: back ser
== [2 3]

red>> index? ser
== 2

red>> ser: back ser
== [1 2 3]

red>> index? ser
== 1

red>> head? ser
== true

top alphanumeric-index category-index



binary!          type:  datatype!--    Cats: Datatypes
The binary! datatype! is a series!.  Each element is a  0-255 
integer value. Literal binary values can be expressed with bases
2, 16, 64. Base 16 is the default.

Because of the byte-based representation, we must supply sufficient digits
to produce 8-bit units. Thus for base 16, we must provide 2, 4, 6 etc
digits, and for base 64, we must supply 4, 8, 12 etc digits. (4 base-64
digits provide 24 bits, which splits into 3 bytes exactly).

The arithmetic functions do not allow binary! arguments.

Literals can be written with white space for readability, and upper or
lower-case letters can be used.

Readers of Rebol documentation should note that Red is closer to Rebol3 in
this area. There are major differences from Rebol2.

Examples
; -------------------------------------------------------------------------
; Some literals
; -------------------------------------------------------------------------

;base 16 - hex
red>> #{0f}
== #{0F}

;base 2, with spaces
>> 2#{11110000 11110000}
== #{F0F0}

;base 64
>> 64#{ffff}
== #{7DF7DF}

;incorrect number of digits here
red>> #{fff}
*** Syntax Error: invalid binary! at "#{fff}"
*** Where: do

; -------------------------------------------------------------------------
; Use to binary!
; -------------------------------------------------------------------------

;convert a string
red>> to binary! "1111ffff"
== #{3131313166666666}

; -------------------------------------------------------------------------
; Use pick to get an integer element (FF)
; -------------------------------------------------------------------------

red>> b: #{00
ff
22
}
== #{00FF22}

red>> pick b 2
== 255

top alphanumeric-index category-index



binary?          type:  function!--    Cats: Type Checking
The word binary? returns true if its argument is of binary! type.
A literal binary series! is surrounded by #{...}
Examples
red>> binary? #{22}
== true

red>> binary? #{ 22 FF AA }
== true

red>> binary? 16
== false

top alphanumeric-index category-index



bind          type:  native!--    Cats: Objects
USAGE:
BIND word context

DESCRIPTION:
Bind words to a context; returns rebound words.
BIND is a native! value.

ARGUMENTS:
word [block! any-word!]
context [any-word! any-object! function!]

REFINEMENTS:
/copy => Deep copy blocks before binding.

RETURNS:
[block! any-word!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



bitset!          type:  datatype!--    Cats: Datatypes
The bitset! datatype provides  an array of bits that is used to store 
boolean values. It is often used with Parse, letting us represent
arbitrary sets of characters across the whole Unicode range, that can be
matched against an input character in a single operation.

In order to create a bitset, you need to provide one or several characters
as a base specification. They can be provided in different forms: codepoint
integer! values, char! values, string! values, a range, or a
group of previous elements.

The bitset! indexing starts at zero. It is not a series! type.

Bitsets expand at the right as needed, to provide enough storage for additions.

A charset! shortcut function is provided for convenience, and is shown
below.

We create a new bitset! with make, and its argument must be one of:

char!, integer!, string! or block!

Examples
; -------------------------------------------------------------------------
; Create some bitsets
; -------------------------------------------------------------------------

; an empty bitset with places at least for 16 bits
;note the 4 hex digits displayed
red>> b-demo: make bitset! 16
== make bitset! #{0000}

; a bitset - space for at least 17 bits. Size is rounded to upper byte bound.
red>> b-demo2: make bitset! 17
== make bitset! #{000000}

; create a bitset with bit 65 set
red>> b-demo: make bitset! #"A" (16 x 0000 bits, then a 0100)
== make bitset! #{000000000000000040}

; create a bitset with bits 104 and 105 set
red>> a-set: make bitset! "hi"
== make bitset! #{00000000000000000000000000C0}

; create and set bits using different values, representations
red>> make bitset! [120 "hello" #"A"]
== make bitset! #{00000000000000004000000004890080}

; create a bitset using ranges of values
red>> bits-09-az: make bitset! [#"0" - #"9" #"a" - #"z"]
== make bitset! #{000000000000FFC0000000007FFFFFE0}
; Ranges are defined using two values (char! or integer! allowed)
; we them separate by a dash word.

; -------------------------------------------------------------------------
; A shortcut charset function is also provided for practical usage,
; -------------------------------------------------------------------------

; so you can write:
red>> hex-set: charset "ABCDEF"
== make bitset! #{00000000000000007E}

red>> set-demo: charset [120 "hello" #"A"]
== make bitset! #{00000000000000004000000004890080}

red>> hyphen-demo: charset [120 "hello" #"A"]
== make bitset! #{00000000000000004000000004890080}

; -------------------------------------------------------------------------
; Auto-sizing. We start with "A", and add a "Z" at the right
; -------------------------------------------------------------------------

red>> b-set: make bitset! "A"
== make bitset! #{000000000000000040}
red>> append b-set "Z"
== make bitset! #{000000000000000040000020}

; now we append a "-". Note that it goes in its proper place,
; not at the rightmost end
red>> append b-set "-"
== make bitset! #{000000000004000040000020}
; note that append modifies the original bitset

; -------------------------------------------------------------------------
; Reading and writing single bits. The path notation can be used
; -------------------------------------------------------------------------

; make a bitset
red>> a-set: make bitset! "ABCDEFG"
== make bitset! #{00000000000000007F}

;do some work on the "A" entry
red>> position: to integer! #"A"
== 65

;look for "A" - true, it is there? Yes.
red>> a-set/:position
== true

;remove it
red>> a-set/:position: false
== false
; look at the set, to prove it
red>> a-set
== make bitset! #{00000000000000003F}

;remove it (no difference, it was not there anyway)
red>> remove/part a-set position
== make bitset! #{00000000000000003F}

; now remove "B", leaving us with CDEFG - 5 bits, in the 1F below
red>> remove/part a-set #"B"
== make bitset! #{00000000000000001F}

; -------------------------------------------------------------------------
; The set functions can also be used:
; -------------------------------------------------------------------------

; union, difference, unique, intersect

; make 2 bitsets to work with
red>> chars: make bitset! "ABCDEFGH"
== make bitset! #{00000000000000007F80}

red>> more-chars: make bitset! "123ABCDEFGHxyz"
== make bitset! #{00000000000070007F800000000000E0}

; find the difference between them - note that 7F8 is missing in result
red>> difference chars more-chars
== make bitset! #{000000000000700000000000000000E0}

; -------------------------------------------------------------------------
; The complement function inverts every bit
; -------------------------------------------------------------------------

red>> a-set: make bitset! "ABCD"
== make bitset! #{000000000000000078}

red>> opposite: complement a-set
== make bitset! [not #{000000000000000078}]

; The original set is unaltered
red>> a-set
== make bitset! #{000000000000000078}

top alphanumeric-index category-index



bitset?          type:  function!--    Cats: Type Checking
The word bitset? returns true if its argument is a bitset! type.
Examples
red>> b: make bitset! [1 3 5]
== make bitset! #{54}

red>> n: [2 3 6]
== [2 3 6]

red>> bitset? b
== true

red>> bitset? n
== false

top alphanumeric-index category-index



block!          type:  datatype!--    Cats: Datatypes
The datatype! block! represents a series! type.

They are enclosed in square brackets [ ] and can run over many lines.

The adagium code = data fits very well for a block!.
A block! is just a block of data, but blocks can also be used
as part of the code.
Examples
; -------------------------------------------------------------------------
; Create a block! with a string!, an integer! and a float! in it.
; -------------------------------------------------------------------------

red>> ["Mike" 55 1.95]
== ["Mike" 55 1.95]

; -------------------------------------------------------------------------
; Use a block! in program code.
; -------------------------------------------------------------------------

red>> if 3 > 2 [print "bigger"]
== bigger

; -------------------------------------------------------------------------
; Code = data
; -------------------------------------------------------------------------

red>> a: 22
== 22

red>> my-block: [4 + a]
== [4 + a] ; Just a data block!

red>> do my-block
== 26 ; Happens to contain valid code!

; -------------------------------------------------------------------------
; Beware of unset! values in a block!
; -------------------------------------------------------------------------

red>> my-data: [name "Li" age 42]
== [name "Li" age 42]

red>> print my-data
*** Script Error: name has no value
*** Where: print

top alphanumeric-index category-index



block?          type:  function!--    Cats: Type Checking
The word block? returns true if its parameter is a 
valid block! or false otherwise.

Has 1 parameter.
Examples
block? "test"
== false

block? [test 1 2 3]
== true

top alphanumeric-index category-index



body-of          type:  function!--    Cats: Functions
The word body-of shows the body of a function! type.

This word is tightly related with the source word.
Examples
red>> x: function [a b] [ a + b ]
== func [a b][a + b]

red>> source x
x: func [a b][a + b]

red>> body-of :x
== [a + b]

red>> source list-dir
list-dir: func [
{Displays a list of files and directories from given folder or current one}
dir [any-type!] "Folder to list"
/col "Forces the display in a given number of columns"
n [integer!] "Number of columns"
/local list max-sz name
][
unless value? 'dir [dir: %.]
unless find [file! word! path!] type?/word :dir [
cause-error 'script 'expect-arg ['list-dir type? :dir 'dir]
]
list: read normalize-dir dir
max-sz: either n [system/console/limit / n - n] [
n: max 1 system/console/limit / 22
22 - n
]
while [not tail? list] [
loop n [
if max-sz <= length? name: list/1 [
name: append copy/part name max-sz - 4 "..."
]
prin tab
prin pad form name max-sz
prin " "
if tail? list: next list [exit]
]
prin lf
]
]

red>> print mold body-of :list-dir
[
unless value? 'dir [dir: %.]
unless find [file! word! path!] type?/word :dir [
cause-error 'script 'expect-arg ['list-dir type? :dir 'dir]
]
list: read normalize-dir dir
max-sz: either n [system/console/limit / n - n] [
n: max 1 system/console/limit / 22
22 - n
]
while [not tail? list] [
loop n [
if max-sz <= length? name: list/1 [
name: append copy/part name max-sz - 4 "..."
]
prin tab
prin pad form name max-sz
prin " "
if tail? list: next list [exit]
]
prin lf
]
]

top alphanumeric-index category-index



break          type:  native!--    Cats: Iteration
The word break breaks out of a loop.

Refinements:
/return : forces the loop function to return the value following.
Examples
; -------------------------------------------------------------------------
; Normal example
; -------------------------------------------------------------------------


foreach number [1 2 4 8 16] [
if number > 8 [break]
print number
]
print "loop 1 teminated"
1
2
4
8
loop 1 teminated

; -------------------------------------------------------------------------
; Contreived example
; -------------------------------------------------------------------------


print foreach number [1 2 4 8 16] [
if number > 8 [break/return -999]
print number
]
print "loop 2 teminated"
1
2
4
8
-999
loop 2 teminated
; The foreach loop returns the value -999,
; which in turn is printed by "print"

top alphanumeric-index category-index



browse          type:  native!--    Cats: URL/Internet
USAGE:
BROWSE url

DESCRIPTION:
Open web browser to a URL or file mananger to a local file.
BROWSE is a native! value.

ARGUMENTS:
url [url! file!] The word browse opens a web browser
with the specified URL.

The single argument is a url!.
; -------------------------------------------------------------------------
; Open a web browser pointing to Google. Execution continues
; -------------------------------------------------------------------------

red>> browse http://www.google.com
red>> ; execution continues here

top alphanumeric-index category-index



call          type:  native!--    Cats: System Related

The word call executes a shell command to run another process.

The argument is:

A command [string! file!] - A shell command or an executable file.

Refinements
/wait - Runs command and waits for exit.
/show - Force the display of system's shell window (Windows only).
/console - Runs command with I/O redirected to console (CLI console only at present).
/shell - Forces command to be run from shell.
/input - we provide a [string! file! binary!], which will be redirected to stdin.
/output - we provide a [string! file! binary!] which will
receive the redirected stdout from the command. Note that the
output is appended.
If you don't want this, clear the destination(or delete the file, for example).

/error - as /output, but redirects stderr.
(Awaiting additional documentation by red-by-example team.)


Examples
; -------------------------------------------------------------------------
; Please note:
; -------------------------------------------------------------------------

; These examples were run on Windows 7. Prints are included,
; to provide confirmation of a call starting and ending.
; File paths that do not begin with a / are relative paths.
; Enclose spaces in " ", or use hex codes
; ( '/' works on GNU/Linux, and Windows)

; -------------------------------------------------------------------------
; Call a non-gui program in current directory. % precedes a file name.
; -------------------------------------------------------------------------

print "The program only displays a message, and is not visible-on-screen"
call %hi-exe.exe
Print "Done 1"

; -------------------------------------------------------------------------
; Call notepad++ editor, with absolute path
; -------------------------------------------------------------------------

print "The notepad++ pops up, and this program continues"
call %"C:/Program Files/notepadPP/notepad++.exe"
print "Done 2"

; -------------------------------------------------------------------------
; Call notepad++ editor, with relative path
; -------------------------------------------------------------------------

call %"../Program Files/notepadPP/notepad++.exe"
print "Done 3"

; -------------------------------------------------------------------------
; Call notepad++, with a command-line argument for it.
; -------------------------------------------------------------------------

call %"C:/Program Files/notepadPP/notepad++.exe myData.txt"
print "Done 4"


; -------------------------------------------------------------------------
; /wait refinement. Call notepad++, wait till user closes it.
; -------------------------------------------------------------------------

print "The notepad++ pops up, and this program continues"
call/wait %"C:/Program Files/notepadPP/notepad++.exe"
print "Done 5"

; -------------------------------------------------------------------------
; /output refinement - redirect output of hi-exe.exe to file hi-out.txt
; -------------------------------------------------------------------------

call/output %hi-exe.exe %hi-out.txt
print "Done 6"


; -------------------------------------------------------------------------
; /output - from a .bat file containing Dos commands (A dir command here)
; -------------------------------------------------------------------------

call/output %bat-demo.bat %dir-out.txt
print "Done 7"

; -------------------------------------------------------------------------
; /output - with the output from a Dos command going to a string
; -------------------------------------------------------------------------

a-string: ""
call/output "dir *.txt" a-string
print ["Dir listing is: " a-string]

; -------------------------------------------------------------------------
; /show - run a command-file. Its window flashes up, then vanishes
; -------------------------------------------------------------------------

call/show %bat-demo.bat
print "Done 8"


top alphanumeric-index category-index



case          type:  native!--    Cats: Conditional branching
The word case provides a multi-way branch structure.  
The block! following the first true condition is evaluated.

The result of a case is the value of the last expression evaluated.

Conditional expressions are supported, rather than the simpler form
in the switch word.

Refinement:
/all : causes the blocks for every true condition to be evaluated.
Examples
; -------------------------------------------------------------------------
; case without /all refinement
; -------------------------------------------------------------------------


n: 555
case [
n < 10 [print "small"]
n < 100 [print "medium"]
n < 1000 [print "large"]
true [print "none of these"]
]
large

; -------------------------------------------------------------------------
; case with /all refinement (1)
; -------------------------------------------------------------------------


n: 555
case/all [
n < 10 [print "small"]
n < 100 [print "medium"]
n < 1000 [print "large"]
true [print "none of these"]
]
large
none of these

; -------------------------------------------------------------------------
; case with /all refinement (2)
; -------------------------------------------------------------------------


n: 555
case/all [
n > 10 [print "small"]
n > 100 [print "medium"]
n > 1000 [print "large"]
true [print "none of these"]
]
small
medium
none of these

top alphanumeric-index category-index



catch          type:  native!--    Cats: Conditional branching, Error
Catches a throw from a block and returns its value. Note  that catch 
and throw are mainly intended for creating new control structures, and
are not the main exception-handling functions. For this, look at attempt,
try, cause-error error?, and error!.

Arguments
The single argument must be a block to evaluate.

Refinements
/name - Catches a named throw. We supply a word or block
of words, which are intended to match a named throw or one of
several named throws.

Examples
; -------------------------------------------------------------------------
; This complete example shows various catch/throw possibilities.
; -------------------------------------------------------------------------

;It is rather artificial - we could get the same effect with
;more 'either' instructions.
;The example has a flavour of exception-handling, but in Red
;we should really use 'try', 'error?' etc for proper exception-handling.
;throw and catch are intended for building control-structures

;a function for the examples.
grade-a-mark: function [
"Convert a % mark to a letter grade, with an un-named throw"
mark [integer!]] [
print ""
print ["In grade-a-mark, with " mark]
if mark > 100 [throw "special"] ;value of the throw is a string
print "about to grade the mark (assume always A for now)"
"A"
]

;Example with no catch - commented out ------------------------

; the code: print grade-a-mark 102
;would cause execution to halt, with this error:
; *** Throw Error: no catch for throw: "special"

print ""
print "Examples with catch and throw (un-named)-----------------"

; catches our throw, but NOT arithmetic errors (e.g. zero-divide)
print catch [grade-a-mark 103] ; prints: too big

;now, take some action after catching, using returnedresult
if (catch [grade-a-mark 104]) = "special" [
print "caught a throw: special"
]

print ""
print "Examples with catch and throw using /name --------------"

;a similar function, with 2 named throws
grade-a-mark-named: function [
"Convert a % mark to a letter grade - version 2 - 2 named throws"
mark [integer!]] [
print ""
print ["In grade-a-mark-named, with " mark]
;throws with a 'word
if mark > 100 [throw/name mark 'special-one] ;throw has a name as well as a value
if mark < 0 [throw/name mark 'too-small]
[print "grade-a-mark-named: about to grade the mark (assume always A for now)"
"A"
]
]

print "Catching any throw, displaying returned value"
print catch [grade-a-mark-named 105]

print "Now catching named throws via 'word argument for refinement"
if (catch/name [grade-a-mark-named 106] 'special-one) [
print "caught a throw named 'special-one"
]

if (catch/name [grade-a-mark -3] 'too-small) [
print "caught a throw named 'too-small"
]

print ""
print "Now catching a selection of named throws"
;because the names are in a block, we don't need the '
if (catch/name [grade-a-mark-named -4] [special-one too-small]) [
print "caught either 'special-one or 'too-small"
]


OUTPUT FROM THE ABOVE:
---------------------

Examples with catch and throw using /name --------------
Catching any throw, displaying returned value

In grade-a-mark-named, with 105
105
Now catching named throws via 'word argument for refinement

In grade-a-mark-named, with 106
caught a throw named 'special-one

In grade-a-mark, with -3
about to grade the mark (assume always A for now)
caught a throw named 'too-small

Now catching a selection of named throws

In grade-a-mark-named, with -4
caught either 'special-one or 'too-small

top alphanumeric-index category-index



cause-error          type:  function!--    Cats: Error
Causes an immediate error, with the provided values.  Note that this is 
not a throw, and cause-error does not co-operate with throw and
catch.

For other error/exception-handling words, look at the related entries for
attempt, try, error?, and the error! type.

Arguments

Here we show how to view the pre-defined Red errors, which can be used as
arguments. The 3 arguments are:

Argument 1: err-type - a word!
This is a general category of error. A list of these can be obtained
by typing the following at the Red console:
words-of system/catalog/errors

which currently displays:
[throw note syntax script math access user internal]

Argument 2: err-id - a word!
The specific error id words in a type can be obtained by typing e.g.:
? system/catalog/errors/math
which displays:
`system/catalog/errors/math` is an object! of value:
code integer! 400
type string! Math Error
zero-divide string! attempt to divide by zero
overflow string! math or number overflow
positive string! positive number required


Argument 3: args - a block!
Some errors take no arguments, and we can supply an empty block. The
zero-divide word above is such an error. However, when we look in the
script type, we see around 70 error words, including, for example:

no-value block! [:arg1 "has no value"]

which takes 1 argument. We can supply any required arguments in a block.


Examples
; -------------------------------------------------------------------------
; Cause some errors. (Abstract examples, no purpose to the errors)
; -------------------------------------------------------------------------


do-work: function [ ] [
sum: 0
;note the empty block for the 3rd argument:
cause-error 'math 'zero-divide []
]
print do-work

*** Math Error: attempt to divide by zero
*** Where: do


do-work: function [ ] [
sum: 0
;note the 3rd argument - often a word, could be e.g. a string.
cause-error 'script 'no-value ['sum]
]
print do-work

*** Script Error: sum has no value
*** Where: do

top alphanumeric-index category-index



cd          type:  function!--    
This word is a synonym for change-dir
top alphanumeric-index category-index


change          type:  action!--    Cats: Series, String manipulation
The word change changes a value in a series! and returns the series beyond
the change position. The original series is changed.

Arguments:
1. series! positioned at the point to change.
2. new value to insert - any type.


Refinements
/part - limits the amount to change to a given length (number) or position (index)
/only - changes a series as a series.
/dup - duplicates the change a specified number of times
Examples
; -------------------------------------------------------------------------
; Changing a string!
; -------------------------------------------------------------------------

red>> s: "abcdef"
== "abcdef"

red>> change s "NEW"
== "def"

red>> s
== "NEWdef"

; -------------------------------------------------------------------------
; Changing a block!
; -------------------------------------------------------------------------

red>> b: [22 33 44 55]
== [22 33 44 55]

red>> change b 11
== [33 44 55]

red>> b
== [11 33 44 55]

red>> b: next head b
== [33 44 55]

red>> change b 10
== [44 55]

red>> b
== [10 44 55]

red>> b: head b
== [11 10 44 55]

; -------------------------------------------------------------------------
; The /part refinement
; -------------------------------------------------------------------------

; -------------------------------------------------------------------------
; The /part refinement, with series as the range. The important thing to
; note here is that the series used for the range MUST refer to the same
; series that is being changed. If it doesn't, CHANGE will throw an error.
; -------------------------------------------------------------------------
red>> s: "abcdef" == "abcdef"
red>> change/part s "ABCD" at s 3 == "cdef"
; the series position limits the length of the part to be replaced
red>> s == "ABCDcdef"

; -------------------------------------------------------------------------
; The /only refinement
; -------------------------------------------------------------------------

red>> s: [11 22 33]
== [11 22 33]

red>> change/only s [1 2]
== [22 33]

red>> s
== [[1 2] 22 33]

; -------------------------------------------------------------------------
; The same example, but without /only
; -------------------------------------------------------------------------

red>> s: [11 22 33]
== [11 22 33]

red>> change s [1 2]
== [33]

red>> s
== [1 2 33]

; -------------------------------------------------------------------------
; The /dup refinement
; -------------------------------------------------------------------------

red>> s: "abcdef"
== "abcdef"

red>> change/dup s "<>" 2
== "ef"

red>> s
== "<><>ef"

top alphanumeric-index category-index



change-dir          type:  function!--    Cats: Directories, Files
The word change-dir changes the current directory.

The argument can be one of file! word! path!.

The directory to change to can be:
- an absolute path!
- a relative path!
Examples
; -------------------------------------------------------------------------
; Using an absolute path
; -------------------------------------------------------------------------

red>> change-dir %/e/src
== %/e/src/

red>> dir
8th/ go/ python/ red/ spiderbasic/

; -------------------------------------------------------------------------
; Using a relative path
; -------------------------------------------------------------------------

red>> change-dir %go
== %/e/src/go/

red>> dir
bin32/ bin64/ pkg/ src/

top alphanumeric-index category-index



char!          type:  datatype!--    Cats: Datatypes
The datatype! char! represents a scalar! type containing 
a single char!.

A literal looks like:
#"A"
Only a single character is valid. So e.g. #"AZ" is invalid!

A series! of char! is a string!.

Representation of the letter A as a:
char! -> #"A"
string! -> "A"

The caret ^ is the escape character for special codes:
- a numeric value is interpreted as HEX
- null, line, tab, page, esc, back, delete
To use such a code, specify:
#"^(code)"

There are some pre-defined characters:

null #"^@"
newline #"^/"
slash #"/"
dbl-quote #"^""
space #" "
lf #"^/"
tab #"^-"
CR #"^M"
dot #"."
escape #"^["
comma #","
sp #" "

Examples
; -------------------------------------------------------------------------
; Some examples
; -------------------------------------------------------------------------

red>> #"A"
== #"A"

red>> print #"A"
A

red>> print #"^(41)" ; Hex 41 is decimal 65 is ASCII A
A

red>> first "dog" ; A char! as element of a string! series!
== #"d"

red>> print #"^(line)" ; Output a blank line


red>> prin 3 prin #"^(tab)" print 6
3 6

red>> #"A" + 1
== #"B"

red>> #"B" > #"A"
== true

top alphanumeric-index category-index



char?          type:  function!--    Cats: Type Checking
The char? word returns true if the value is a char! type. 
Examples
red>> char? 33
== false
; 33 is a number and thus not a char!

red>> char? #"A"
== true

red>> char? "AB"
== false
; "AB" is a string, which is a series type

top alphanumeric-index category-index



charset          type:  function!--    Cats: Sets
The word charset is a helper function for the bitset! type.  

In Red, the main use of bitsets is with character sets (possibly
across the whole Unicode range).

The charset function provides simplified creation with ranges.

In cases when it is tedious to create massive bitsets (perhaps with huge
numbers of Unicode characters) we can create complemented sets, using not.

The single argument can be:
block! integer! char! string!
We can also use the hyphen "-" to specify ranges.
Examples
; -------------------------------------------------------------------------
; Create some bitsets with charset
; -------------------------------------------------------------------------

red>> vowels: charset ["AEIOU"]
== make bitset! #{0000000000000000444104}

red>> digits: charset ["0123456789"]
== make bitset! #{000000000000FFC0}

; -------------------------------------------------------------------------
; Use a range, with -
; -------------------------------------------------------------------------

red>> alpha: charset [#"A" - #"Z" #"a" - #"z"]
== make bitset! #{00000000000000007FFFFFE07FFFFFE0}
red>>

; -------------------------------------------------------------------------
; Mixed types
; -------------------------------------------------------------------------

red>> set-demo: charset [120 "hello" #"A"]
== make bitset! #{00000000000000004000000004890080}

; -------------------------------------------------------------------------
; Complementing -> all unicode characters except these 10
; -------------------------------------------------------------------------

red>> charset [not "0123456789"]
== make bitset! [not #{000000000000FFC0}]

top alphanumeric-index category-index



checksum          type:  native!--    Cats: Network
The word checksum computes a checksum, CRC, hash, or HMAC. 

Arguments
1. data = binary!, string! or file!
2. the checksum method - a word:
MD5 SHA1 SHA256 SHA384 SHA512 CRC32 TCP hash.

Refinements
/with - extra value for HMAC key or hash table size;
not compatible with TCP/CRC32 methods.
The value we supply can be:
any-string! binary! integer!
string or binary for MD5/SHA* HMAC key
integer! for hash table size.
Examples
; -------------------------------------------------------------------------
; Do a CRC and MD5 checksum
; -------------------------------------------------------------------------

red>> checksum "some text" 'CRC32
== 1337638330

red>> checksum "some text" 'MD5
== #{552E21CD4CD9918678E3C1A0DF491BC3}

top alphanumeric-index category-index



clean-path          type:  function!--    Cats: Directories, Files
The word clean-path cleans-up '.' and '..' in a path 
and returns the cleaned path.

The argument can be:
file! url! string!

Refinements
/only - do not prepend current directory.
/dir - add a trailing / if missing.
Examples
; -------------------------------------------------------------------------
; Remove some redundant parent (..) and current(.) uses.
; -------------------------------------------------------------------------

red>> clean-path %/folder1/folder2/folder3/../../file.txt
== %/folder1/file.txt

red>> clean-path %/folder1/folder2/././file.txt
== %/folder1/folder2/file.txt

; -------------------------------------------------------------------------
; The /dir refinement
; -------------------------------------------------------------------------

red>> clean-path/dir %/folder1/folder2
== %/folder1/folder2/

; -------------------------------------------------------------------------
; The /only refinement
; -------------------------------------------------------------------------

red>> clean-path/only %folder1/file.txt
== %file.txt

red>> clean-path %folder1/file.txt ; without /only
== %/C/red/folder1/file.txt

; -------------------------------------------------------------------------
; Clean up a URL
; -------------------------------------------------------------------------

red>> clean-path http://www/./google.com
== %/www/google.com

top alphanumeric-index category-index



clear          type:  action!--    Cats: Series, String manipulation
The word clear deletes the contents of a series starting from the current
index.
Examples
; -------------------------------------------------------------------------
; Clear a string!
; -------------------------------------------------------------------------

red>> s: "abcdefghijklm"
== "abcdefghijklm"

red>> clear s
== ""

red>> s
== ""

; -------------------------------------------------------------------------
; Clear part of a series!
; -------------------------------------------------------------------------

red>> n: [1 2 3 4 5 6 7]
== [1 2 3 4 5 6 7]

red>> clear skip n 3
== []

red>> n
== [1 2 3]

; -------------------------------------------------------------------------
; Clear from a found position
; -------------------------------------------------------------------------

red>> s: "the quick brown fox jumps over the lazy dog"
== "the quick brown fox jumps over the lazy dog"

red>> clear find s "jumps"
== ""

red>> s
== "the quick brown fox "

top alphanumeric-index category-index



clear-reactions          type:  function!--    Cats: Reactivity
USAGE:
CLEAR-REACTIONS

DESCRIPTION:
Removes all reactive relations.
CLEAR-REACTIONS is a function! value.
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



collect          type:  function!--    Cats: Series, String manipulation
Collect in a new block all the values passed to the 'keep' function from 
the body block. We often use collect and keep in parse.

Argument

A body block! to evaluate.

Refinements

/into - Insert into a buffer instead (returns position after insert).
We supply a series!, which will be modified.

Examples
;create a block, with no keeps
red>> b: [4 3 * 3 (3 * 10) (5 * 100)]

;nothing to collect
red>> collect b
== []

;now use keep
red>> b: [keep 4 3 * 3 keep (3 * 10) (5 * 100)]

;note the 'kept' items
red>> collect b
== [4 30]

; try the /into refinement
; buf for /into
red>> buf: ["item 1"]

red>> b
== [keep 4 3 * 3 keep (3 * 10) (5 * 100)]
red>> collect/into b buf
== ["item 1" 4 30]

;note value of buf
red>> buf
== ["item 1" 4 30]

top alphanumeric-index category-index



comma          type:  char!--    Cats: Constants
A pre-defined char! value.

See char!

top alphanumeric-index category-index



comment          type:  function!--    Cats: Documentation
The word comment introduces a comment in a Red program.

It has the form:
comment {
... multi-line comment ...
}
or:
comment " ... single-line comment ... "
Examples
comment { 
This is a multi-line comment,
consisting of more than one line.
}

comment "And this is a single-line comment!"


top alphanumeric-index category-index



complement          type:  action!--    Cats: Bit manipulation
The word complement returns the complement of the argument.

Has one argument, of type:
logic! integer! bitset! typeset!

For logic!, it returns true or false.

For values with an accessible bit representation, it returns the
"ones complement".
Examples
; -------------------------------------------------------------------------
; With logic!
; -------------------------------------------------------------------------


red>> complement 3 > 2
== false

; -------------------------------------------------------------------------
; With integer!s
; -------------------------------------------------------------------------


red>> complement 2
== -3

red>> complement -1
== 0

red>> complement 63
== -64

; -------------------------------------------------------------------------
; With bitset!
; -------------------------------------------------------------------------


red>> b: make bitset![0 1]
== make bitset! #{C0}

red>> complement b
== make bitset! [not #{C0}]

top alphanumeric-index category-index



complement?          type:  native!--    Cats: Type Checking
The word complement? returns true if the bitset is 
complemented (that is: inverted with not).
Examples
red>> vowels: charset ["AEIOU"]
== make bitset! #{0000000000000000444104}

red>> complement? vowels
== false

red>> non-digits: charset [ not "0123456789"]
== make bitset! [not #{000000000000FFC0}]

red>> complement? non-digits
== true

top alphanumeric-index category-index



compose          type:  native!--    Cats: Series, String manipulation
Returns a copy of a block, evaluating only paren! items. Here is an 
example of a paren!, containing 3 elements:

(2 + 4)

Normally, it does not operate on nested blocks.

The single argument should be a block!

Refinements
/deep - compose nested blocks. All paren! expressions are evaluated,
however deeply they are nested inside [ ].
/only - compose a nested block as a single block containing its values,
rather than its series of values.
/into - put results into a target block, instead of creating a new
block. We supply the target block. This is intended for
very large blocks, and can result in lower memory usage.


Examples
; -------------------------------------------------------------------------
; compose some blocks
; -------------------------------------------------------------------------

red>> compose [unevaluated items 1 + 2 then (3 * 5)]
== [unevaluated items 1 + 2 then 15]
;nested blocks are not evaluated
red>> compose [(1 + 2) [(4 + 5)]]
== [3 [(4 + 5)]]

; -------------------------------------------------------------------------
; /deep refinement
; -------------------------------------------------------------------------

red>> b: [cat [dog (3 * 4) [fish (6 * 7)]]]
red>> compose/deep b
== [cat [dog 12 [fish 42]]]

;note the result without /deep
red>> compose b
== [cat [dog (3 * 4) [fish (6 * 7)]]]

; -------------------------------------------------------------------------
; /only refinement
; -------------------------------------------------------------------------

red>> powers: [1 2 4 8 16]
red>> compose/only [a b c (powers)]
;note [...] round powers values
;without /only, no [ ]
== [a b c [1 2 4 8 16]]
red>> compose [a b c (powers)]
== [a b c 1 2 4 8 16]

; -------------------------------------------------------------------------
; /into refinement a trivial example, insignificant memory use.
; -------------------------------------------------------------------------

red>> b: [aa bb (3 * 4)]

;create an empty block
red>> answer: copy []
== []
red>> compose/into b answer
== []
and here is the result
red>> answer
== [aa bb 12]

top alphanumeric-index category-index



construct          type:  native!--    Cats: Objects
USAGE:
CONSTRUCT block

DESCRIPTION:
Makes a new object from an unevaluated spec; standard logic words are
evaluated.
CONSTRUCT is a native! value.

ARGUMENTS:
block [block!]

REFINEMENTS:
/with => Use a prototype object.
object [object!] "Prototype object."
/only => Don't evaluate standard logic words.
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



context          type:  function!--    Cats: Objects
The word context is a shorter form of make object!.

Using context it is very easy to "hide" variables and functions from
the global naming scope.
Examples
; -------------------------------------------------------------------------
; Show that both forms are equal
; -------------------------------------------------------------------------

red>> x: context [a: 1 b: 2]
== make object! [
a: 1
b: 2
]

red>> y: make object! [a: 1 b: 2]
== make object! [
a: 1
b: 2
]

red>> x = y
== true

; -------------------------------------------------------------------------
; Reference fields in a context
; -------------------------------------------------------------------------

red>> x/a
== 1

red>> x/b
== 2

red>> y/a
== 1

red>> y/b
== 2

; -------------------------------------------------------------------------
; Use a function in a context
; -------------------------------------------------------------------------

red>> p: context [x: 5 y: 6 f: function [] [x + y]]
== make object! [
x: 5
y: 6
f: func [][x + y]
]

red>> p/f ; Uses the x and y in the scope of the context
== 11

red>> p/x: 20 ; Update a field
== 20

red>> p/f
== 26

top alphanumeric-index category-index



context?          type:  native!--    Cats: Type Checking
USAGE:
CONTEXT? word

DESCRIPTION:
Returns the context in which a word is bound.
CONTEXT? is a native! value.

ARGUMENTS:
word [any-word!] "Word to check."

RETURNS:
[object! function! none!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



continue          type:  native!--    Cats: Iteration
The word continue transfers control back to the begin of a loop.
Examples
repeat n 5 [
print ["Before" n]
if n < 3 [continue]
print ["After" n]
]
Before 1
Before 2
Before 3
After 3
Before 4
After 4
Before 5
After 5

top alphanumeric-index category-index



copy          type:  action!--    Cats: Series, String manipulation
The word copy returns a copy of a series! or bitset!.

The word copy does not work on single items such as:
integer! float! char! etc.
For these, we can simply use the colon (get word).

It has one argument of an appropriate type.

For (potentially large) series!, Red works with references
(pointers to series!) rather than directly with the contents.

Refinements
/part - limit the length of the result,
where length is a number! or series!
/deep - copy nested values also
/types - copy only specific types of non-scalar values.
Examples
red>> b: [1 2 3 4]
== [1 2 3 4]
; Create variable b which points to a new block

red>> b2: b
== [1 2 3 4]
; Assign variable b2 to point to the same block that b points to.

red>> b/2: -999
== -999
; Modify the block that b points to at position 2.

red>> b
== [1 -999 3 4]
; As expected b now points to the changed block

red>> b2
== [1 -999 3 4]
; Because b2 points to the same block you see the same change there also!

red>> b: [1 2 3 4]
== [1 2 3 4]
; Create variable b which points to a new block.

red>> b2: copy b
== [1 2 3 4]
; Create variable b2 which points to a copy of the block b points to.

red>> b/2: -999
== -999
; Show that the block that b points to has changed

red>> b2
== [1 2 3 4]
; Because of the copy the block b2 points to is not modified this time.

red>> s: "a string"
== "a string"
; Create variable s pointing to a string.

red>> s2: copy s
== "a string"
; Create variable s2 pointing to a copy of the string that s points to.

red>> a: [22 33 "name" [44 1.34]]
== [22 33 "name" [44 1.34]]
; Create variable a that points to a new block.

red>> b: copy a
== [22 33 "name" [44 1.34]]
; Create variable b and point it to a new copy to the block that a points to.

red>> b: copy/part a 2
== [22 33]
; Only the first 2 items of a are copied!

top alphanumeric-index category-index



cos          type:  function!--    
This word is a synonym for cosine
top alphanumeric-index category-index


cosine          type:  native!--    Cats: Math
The word cosine returns the trigonometric cosine.

Has 1 parameter, a number! (representing an angle).

Refinements:
/radians : expects the input angle in radians;
without refinement expects the input angle in degrees.
Examples
cosine 90
== 0.0

cosine/radians pi
== -1.0

top alphanumeric-index category-index



CR          type:  char!--    Cats: Constants
A pre-defined char! value.

See char!

top alphanumeric-index category-index



create-dir          type:  routine!--    Cats: Files
To do by red-by-example team ...


top alphanumeric-index category-index



datatype!          type:  datatype!--    Cats: Datatypes
The word datatype! is the "mother" of all Red's datatypes.

Note that a typeset! can be defined for grouping several datatypes!

Note that datatype! and typeset! are also a datatype!!
Examples
red>> ? datatype!
action! binary! bitset! block! char!
datatype! error! event! file! float!
function! get-path! get-word! hash! image!
integer! issue! lit-path! lit-word! logic!
map! native! none! object! op!
pair! paren! path! percent! point!
refinement! routine! set-path! set-word! string!
time! tuple! typeset! unset! url!
vector! word!

top alphanumeric-index category-index



datatype?          type:  function!--    Cats: Type Checking
The word datatype? returns true if its argument is a 
datatype! (e.g. integer!, char! etc).
Examples
Examples

red>> datatype? 123
== false

red>> datatype? integer!
== true

red>> datatype? block!
== true

top alphanumeric-index category-index



date!          type:  datatype!--    Cats: Date/Time
Values of the date! represent calendar dates, relying on the Gregorian 
calendar. A date value can also contain optional time and timezone information.
Time in dates is expressed in 24-hour format (including optional time zone
information).

There are a number of date input formats (literals), and we can also construct
dates with make. Calculations can be performed with dates. The current
date and time can be obtained with now.

Path accessors (such as /day, /time ) are available to pick out parts of a date

There are lots of options, and the full documentation is at:
https://doc.red-lang.org/en/date.html

Examples

; -------------------------------------------------------------------------
; Some of the date literal formats, plus an incorrect one.
; -------------------------------------------------------------------------

>> d: 23-Oct-2042
== 23-Oct-2042
>> d: 3-July-2021
== 3-Jul-2021
>> d: 29-February-2017 ;-- not leap year
*** Script Error: cannot MAKE/TO date! from: [day month year]
*** Where: do
*** Stack: load

; -------------------------------------------------------------------------
; Some path accessors
; -------------------------------------------------------------------------

>> appointment: 3/May/2017/6:00:00 ;-- date with time
== 3-May-2017/6:00:00
>> appointment/month
== 5
>> appointment/hour
== 6

; -------------------------------------------------------------------------
; Make a date!
; -------------------------------------------------------------------------

>> any-day: 23
>> month: 2
>> d: make date![any-day month 2017]
== 23-Feb-2017

; -------------------------------------------------------------------------
; Date arithmetic
; -------------------------------------------------------------------------

>> d: now ;-- today's date
== 10-Sep-2017/16:20:04+01:00
>> d + 23:00 ;-- add 23 hours
== 11-Sep-2017/15:20:04+01:00

; -------------------------------------------------------------------------
; Date comparison, with e.g. < and >
; -------------------------------------------------------------------------

>> today: now
== 10-Sep-2017/11:25:24+01:00
>> later: today + 48:00
== 12-Sep-2017/11:25:24+01:00
>> later < today ;-- as expected
== false
>> later > today ;-- as expected
== true


top alphanumeric-index category-index



date?          type:  function!--    Cats: Date/Time, Type Checking
USAGE:
DATE? value

DESCRIPTION:
Returns true if the value is this type.
DATE? is a function! value.

ARGUMENTS:
value [any-type!]

; -------------------------------------------------------------------------
; date?
; -------------------------------------------------------------------------

>> d: 3-May-2019
>> date? d
== true
>> date? "30-May-2019"
== false

top alphanumeric-index category-index



dbl-quote          type:  char!--    Cats: Constants
A pre-defined char! value.

See char!

top alphanumeric-index category-index



debase          type:  native!--    Cats: Bases of Numbers, Conversion
Documentation can be found with the word enbase.

top alphanumeric-index category-index



decompress          type:  native!--    Cats: Compression
USAGE:
DECOMPRESS data

DESCRIPTION:
Decompresses data. Data in GZIP format (RFC 1952) by default.
DECOMPRESS is a native! value.

ARGUMENTS:
data [binary!]

REFINEMENTS:
/zlib => Data in ZLIB format (RFC 1950).
size [integer!] "Uncompressed data size."
/deflate => Data in DEFLATE format (RFC 1951).
size [integer!] "Uncompressed data size."
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



dehex          type:  native!--    Cats: Conversion, URL/Internet
The word dehex converts URL-style hex encoded (%xx) strings 
into characters. The argument can be a string! or a file!.
Examples
red>> dehex "%41BC"                     
== "ABC"
; 41 is hex for A

red>> dehex "www.search.com/for%20this"
== "www.search.com/for this"
; Hex 20 is space

red>> dehex %my%20file.txt
== "my file.txt"
; file! type

top alphanumeric-index category-index



delete          type:  action!--    Cats: Directories, Files
Deletes the specified file or empty folder. Returns false if the item
does not exist.

Arguments
A file!

Examples

; -------------------------------------------------------------------------
; delete: fffff.red does not exist, ttt.red does exist
; -------------------------------------------------------------------------

>> delete %fffff.red
== false
>> delete %ttt.red
== true

top alphanumeric-index category-index



difference          type:  native!--    Cats: Sets
The word difference returns the elements of two series 
that are not present in both.

Both series arguments must be of the same datatype, which
can be:
block! hash! string! bitset! typeset!.

difference in one of several set-style functions.

Refinements:
/case - use case-sensitive comparison.
/skip - treat the series! as fixed size records.
Specify the size as an integer!.
Examples
red>> difference [1 2 99 4] [1 2 3 4]
== [99 3]

red>> difference ["cat" "dog"] ["dog" "mouse" "fish"]
== ["cat" "mouse" "fish"]

red>> difference "abcd" "Ab"
== "cd"

red>> difference/case "abcd" "Ab"
== "acdA"

top alphanumeric-index category-index



dir          type:  function!--    Cats: Directories, Files
The word dir lists the contents of a directory.

It is tightly related to the word list-dir.

The directory to list to can be:
- an absolute path
- a relative path!

If no argument given, it lists the current directory.
Examples
; -------------------------------------------------------------------------
; Using an absolute path
; -------------------------------------------------------------------------

red>> dir %/e/src
8th/ go/ python/ red/
spiderbasic/

; -------------------------------------------------------------------------
; Using it without an argument lists the current directory
; -------------------------------------------------------------------------

red>> dir
basehtml.txt colors.txt design/ gensite.red
gensite.txt pages/ publish/ redftp.lnk
rexec.red tst.red words/

top alphanumeric-index category-index



dir?          type:  function!--    Cats: Directories, Files, Type Checking
The word dir? returns true if the supplied name is a valid file path!, 
otherwise returns false.

A valid file path! must have a trailing /.

NOTE dir? does not look in the file system at all. It only tells you if the
path! is a valid directory path! with a trailing slash!

Has 1 parameter, which must be a valid file path!.
Examples
; Non-existent directory
; Returns false because trailing / is missing
dir? %/c/rubbish
== false
; Returns true because trailing / is present
dir? %/c/rubbish/
== true

; Existing directory
; Returns false because trailing / is missing
dir? %/c/windows
== false
; Returns true because trailing / is present
dir? %/c/windows/
== true

top alphanumeric-index category-index



dirize          type:  function!--    Cats: Conversion, Directories, Files
The word dirize turns its argument into a valid directory.

The argument can be of file! string! url!.

Effectively dirize only appends a trailing / if needed.
Examples
red>> dirize "/e/src"
== "/e/src/" ; Note trailing / appended

red>> dirize %/e/src
== %/e/src/ ; Note trailing / appended

red>> dirize %/e/src/
== %/e/src/ ; Nothing happened - directory was already valid

red>> dirize %.
== %./ ; Note trailing / appended

top alphanumeric-index category-index



divide          type:  action!--    Cats: Math
The word divide returns the first value divided by the second.
This is equivalent to the infix operator /.

Has 2 arguments, which must be of the type:
number! char! pair! tuple! vector!

When a combination of integer! and float! values are divided, the result
is a float!.

When integer!s are divided, the result is an integer!, truncated toward zero.

Division by zero produces a run-time error.
Examples
red>> divide 8 3.0
== 2.666666666666667

red>> divide 8 3
== 2

red>> divide -8 3
== -2

red>> divide 4.5.6 2
== 2.2.3

red>> v: make vector![4 2 8]
== make vector! [4 2 8]

red>> divide v make vector![1 2 3 4]
== make vector! [4 1 2]

red>> v2: make vector![ 2 2 3]
== make vector! [2 2 3]

red>> divide v v2
== make vector! [2 1 2]

top alphanumeric-index category-index



do          type:  native!--    Cats: Evaluation
The word do evaluates the code in its argument.

Single argument:
1. can be a script to execute;
in that case the /args refinement can be used to specify arguments
for that script (a string! or a block!)
2. can be a string! or a block! containing Red code to be
evaluated

Refinements:
/args - arguments for script to be invoked
Examples
; -------------------------------------------------------------------------
; Evaluate a script
; -------------------------------------------------------------------------


; Given a separate script %tst.red:

; Red []
; print "Hi there from %tst.red!"
; args: system/script/args
; print ["My arguments are:" system/script/args]
; if not none? system/script/args [
; foreach arg system/script/args [
; print ["Arg:" arg]
; ]
; ]

; You can evaluate the script without arguments like so:
red>> do %tst.red
Hi there from %tst.red!
My arguments are: none
== none

; You can evaluate the script with string! argument like so:
red>> do/args %tst.red "my args"
Hi there from %tst.red!
My arguments are: my args
Arg: m
Arg: y
Arg:
Arg: a
Arg: r
Arg: g
Arg: s

; If you need multiple arguments, use a block!
red>> do/args %tst.red ["my" "individual" "args"]
Hi there from %tst.red!
My arguments are: my individual args
Arg: my
Arg: individual
Arg: args

; -------------------------------------------------------------------------
; Evaluate a block
; -------------------------------------------------------------------------


red>> blk: [x: 10 y: 20 z: x + y print z]
== [x: 10 y: 20 z: x + y print z]
red>> do blk
30
red>> x
== 10
red>> y
== 20
red>> z
== 30

; -------------------------------------------------------------------------
; Evaluate a string
; -------------------------------------------------------------------------


; Here we show how to do complex things using do

; Use variables to contain the name and value for a variable
; to be embedded in the object
red>> var: "vname"
== "vname"
red>> val: 11
== 11

; Prepare the string with the code
red>> str: copy {obj: make object! [}
== "obj: make object! ["
red>> append str var
== "obj: make object! [vname"
red>> append str copy {: }
== "obj: make object! [vname: "
red>> append str val
== "obj: make object! [vname: 11"
red>> append str copy {]}
== "obj: make object! [vname: 11]"

; String is now complete
red>> str
== "obj: make object! [vname: 11]"

; Evaluate the string
red>> do str
== make object! [
vname: 11
]

; Show that the object now exists:
red>> obj
== make object! [
vname: 11
]
red>> obj/vname
== 11

top alphanumeric-index category-index



do-safe          type:  function!--    Cats: Evaluation
USAGE:
DO-SAFE code

DESCRIPTION:
Internal Use Only.
DO-SAFE is a function! value.

ARGUMENTS:
code [block!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



do-thru          type:  function!--    Cats: Evaluation, URL/Internet
USAGE:
DO-THRU url

DESCRIPTION:
Evaluates a remote Red script through local disk cache.
DO-THRU is a function! value.

ARGUMENTS:
url [url!] "Remote file address."

REFINEMENTS:
/update => Force a cache update.
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



does          type:  native!--    Cats: Functions
The word does defines a function with no arguments or 
local variables.
Examples
welcome: does [
print "Welcome"
print "to Red"
]

welcome
Welcome
to Red

top alphanumeric-index category-index



dot          type:  char!--    Cats: Constants
A pre-defined char! value.

See char!

top alphanumeric-index category-index



either          type:  native!--    Cats: Conditional branching
The word either evaluates a conditional expression. 
If the result thereof is true the first block! will be evaluated.
If false the second block! will be evaluated.

Has 3 parameters, a conditional expression and 2 block!s

either returns the value returned from the conditionally evaluated block!.
Examples
either 3 > 2 [print "Indeed!"][print "Nope!"]
Indeed!

either "ABC" = "abc" [print "The same!"] [print "Different!"]
The same!
; Be careful! Contrary to what is common use in most other programming
; languages, Red considers uppercase and lowercase letters to be equal.

either 2 = 2.0 [print "Equal!"][print "Not equal!"]
Equal!

either 2 == 2.0 [print "Equal!"][print "Not equal!"]
Not equal!

top alphanumeric-index category-index



ellipsize-at          type:  function!--    Cats: String manipulation
USAGE:
ELLIPSIZE-AT str len

DESCRIPTION:
Truncate and add ellipsis if str is longer than len.
ELLIPSIZE-AT is a function! value.

ARGUMENTS:
str [string!] "(modified)."
len [integer!] "Max length."

; -------------------------------------------------------------------------
; ellipsize-at
; -------------------------------------------------------------------------

>> ellipsize-at "abcdefghijk" 8
== "abcd..."


top alphanumeric-index category-index



email!          type:  datatype!--    Cats: Datatypes, URL/Internet
This datatype! lets us represent literal email addresses.  Note that no 
detailed syntax-checking is performed. It must contain an @ character. An
email! is a series!, and can be manipulated character-by-character.

pre.
; -------------------------------------------------------------------------
; Create some email! types, explore them.
; -------------------------------------------------------------------------

; Create, use type? email?
>> e: a@bb.ccc== a@bb.ccc
>> type? e
== email!
>> email? e
== true
; As a series
>> third e
== #"b"
;limited checking
>> em: @x
== @x
>> type? em
== email!


top alphanumeric-index category-index



email?          type:  function!--    Cats: Type Checking
This function returns true if its argument is an email!  datatype!, 
otherwise false.

Arguments

Its single argument can be anytype!.

Examples
; -------------------------------------------------------------------------
; explore email?
; -------------------------------------------------------------------------


;some 'true' email! values
>> em: a@bb.ccc
== a@bb.ccc
>> email? em
== true

>> email? a@b
== true

>> email? a@
== true

;'false' email literal
>> email? "a@b" ;string
== false



top alphanumeric-index category-index



empty?          type:  function!--    Cats: Series, String manipulation, Type Checking
The word empty? checks whether a series! is empty.
Examples
; -------------------------------------------------------------------------
; A few examples
; -------------------------------------------------------------------------

red>> empty? []
== true

red>> empty? [1] ; Not empty - contains a number
== false

red>> empty? [ [] ] ; Not empty - contains a block!
== false

red>> empty? "x" ; Not empty - contains a character
== false

red>> empty? ""
== true

red>> empty? { "" } ; Not empty - contains a 4 character string
== false

top alphanumeric-index category-index



enbase          type:  native!--    Cats: Bases of Numbers, Conversion
The word enbase encodes a string to a a binary-coded string (BASE-64 default).
Argument:
string to be encoded
Refinement:
/base - base to be used, e.g. 2, 16 or 64 (default)

The word debase decodes a binary-coded to a binary (BASE-64 default).
Argument:
binary-coded string to be decoded
Refinement:
/base - base to be used, e.g. 2, 16 or 64 (default)
Examples
; -------------------------------------------------------------------------
; Default base-64 decoding
; -------------------------------------------------------------------------

red>> x: enbase "Red is beautiful"
== "UmVkIGlzIGJlYXV0aWZ1bA=="

red>> y: debase x
== #{5265642069732062656175746966756C}

red>> to string! y
== "Red is beautiful"

; -------------------------------------------------------------------------
; The /base refinement
; -------------------------------------------------------------------------

red>> x: enbase/base "Red is beautiful" 2
== {0101001001100101011001000010000001101001011100110010000001100010
0110010101100001011101010111010001101001011001100111010101101100}

red>> y: debase/base x 2
== #{5265642069732062656175746966756C}

red>> to string! y
== "Red is beautiful"

; -------------------------------------------------------------------------
; Note that debase needs fixed length chunks!
; -------------------------------------------------------------------------

; for base 2: multiple of 8 bits
; for base 16: multiple of 8 bits
; for base 64: multiple of 16 bits

red>> x: enbase/base "A" 2
== "01000001"

red>> y: debase/base x 2 ; works, because bitstring is a multiple of 8 (bits)
== #{41}

red>> to string! y
== "A"

red>> debase/base "01000001" 2 ; same as contents of y
== #{41}

red>> debase/base "010000011" 2 ; 9 bits - won't work
== none

red>> debase/base "0100001" 2 ; 7 bits - won't work
== none

top alphanumeric-index category-index



equal?          type:  native!--    Cats: Comparison, Type Checking
The word equal? returns true if two values are equal.  

This is the functional form of the infix word =. Look
there for more details.
Examples
red>> equal? [1 2 3] [1 2 3]
== true

top alphanumeric-index category-index



error!          type:  datatype!--    Cats: Datatypes
The word error! is a datatype!.

Red supports first class errors via this datatype!.

Errors can be generated by the user or produced by the system.
The error definitions are stored in the system/catalog/errors object.

Here is how we can view the definitions:
red>> help system/catalog/errors
system/catalog/errors` is an object! of value:
throw object! [code type break return throw continue]
note object! [code type no-load]
syntax object! [code type invalid missing no-header no-rs-h...
script object! [code type no-value need-value not-defined n...
math object! [code type zero-divide overflow positive]
access object! [code type cannot-open invalid-utf8 no-conne...
user object! [code type message]
internal object! [code type bad-path not-here no-memory stack...
red>>

To see the list of errors concerning 'math' for example, we type:
? system/catalog/errors/math

User errors can be created using 'make' followed by an error integer code,
or a block containing the category, error name and (for some errors) an error argument.
Examples
; -------------------------------------------------------------------------
; Error code
; -------------------------------------------------------------------------

red>> make error! 402
*** Math error: attempt to divide by zero
*** Where: ???

; -------------------------------------------------------------------------
; Error name
; -------------------------------------------------------------------------

red>> make error! [math zero-divide]
*** Math error: attempt to divide by zero
*** Where: ???

; -------------------------------------------------------------------------
; Using type, id, and argument
; -------------------------------------------------------------------------

red>> make error! [type: 'script id: 'no-value arg1: 'x]
*** Script Error: x has no value
*** Where: ???

top alphanumeric-index category-index



error?          type:  function!--    Cats: Error, Type Checking
The word error? returns true if the value is of 
type error!. Otherwise false is returned.

This can be used to check the result from try.
Examples
red>> error? try [2 + "3"]
== true

red>> error? try[2 + 3]
== false

top alphanumeric-index category-index



escape          type:  char!--    Cats: Constants
A pre-defined char! value.

See char!

top alphanumeric-index category-index



eval-set-path          type:  function!--    Cats: Evaluation
USAGE:
EVAL-SET-PATH value1

DESCRIPTION:
Internal Use Only.
EVAL-SET-PATH is a function! value.

ARGUMENTS:
value1
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



even?          type:  action!--    Cats: Math
The word even? returns true if a number! is even.
Else returns false.

Arguments

Has 1 argument: a number!, char!, or time!.
Examples
even? -4
== true

even? 77
== false

top alphanumeric-index category-index



event!          type:  datatype!--    Cats: Datatypes
Event! values are object-like values that represent external activity.

Look in the official View documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



event?          type:  routine!--    Cats: Type Checking
USAGE:
EVENT? value

DESCRIPTION:
Returns true if the value is this type.
EVENT? is a routine! value.

ARGUMENTS:
value [any-type!]

RETURNS:
[logic!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



exclude          type:  native!--    Cats: Series, String manipulation
The word exclude returns a new value, which is the first 
argument where elements of the second argument are excluded.

With strings, difference in case is not significant.

The argument types can be:
block! hash! string! bitset! typeset!

Refinements:
/case - use case sensitive comparison.
/skip - treat the series! as fixed size records.
Specify the size as an integer!.
Examples
red>> exclude [1 2 3 4 5 6] [2 4 6]
== [1 3 5]
; Exclude evens

red>> exclude "The Great Wall Of China" "aeiou"
== "Th GrWlfCn"
; Exclude vowels, ignoring case

red>> exclude/case "The Great Wall Of China" "aeiou"
== "Th GrtWlOfCn"
; Exclude vowels, regarding case - note the letter "O"

top alphanumeric-index category-index



exists-thru?          type:  function!--    Cats: Files, URL/Internet
USAGE:
EXISTS-THRU? url

DESCRIPTION:
Returns true if the remote file is present in the local disk cache.
EXISTS-THRU? is a function! value.

ARGUMENTS:
url [url! file!] "Remote file address."
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



exists?          type:  routine!--    Cats: Directories, Files
The word exists? returns true if its argument is an existing path!
or false otherwise.
Examples
red>> exists? %/e/drunk
== false

red>> exists? %/e/src
== true

top alphanumeric-index category-index



exit          type:  native!--    Cats: Exiting, Functions
The word exit exits a function! without returning a value.

Has no parameters.
Examples
fun1: func [p1] [
fun2 p1
print "fun2 completed"
]

fun2: func [p2] [
print "Before exit check ..."
if p2 = "exit" [exit]
print "After exit check"
]

fun1 "abc"
Before exit check ...
After exit check
fun2 completed

fun1 "exit"
Before exit check ...
fun2 completed

top alphanumeric-index category-index



exp          type:  native!--    Cats: Math
The word exp raises E (the natural number) to the power supplied.

Has one number! parameter.
Examples
x: exp 0
== 1.0

x: exp 1
== 2.71828182845905

exp -1
== 0.367879441171442

top alphanumeric-index category-index



expand          type:  function!--    Cats: Macros
USAGE:
EXPAND blk

DESCRIPTION:
Preprocess the argument block and display the output (console only).
EXPAND is a function! value.

ARGUMENTS:
blk [block!] "Block to expand."
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



expand-directives          type:  function!--    Cats: Macros
USAGE:
EXPAND-DIRECTIVES code

DESCRIPTION:
Invokes the preprocessor on argument list, modifying and returning it.
EXPAND-DIRECTIVES is a function! value.

ARGUMENTS:
code [block! paren!] "List of Red values to preprocess."

REFINEMENTS:
/clean => Clear all previously created macros and words.
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



extend          type:  native!--    Cats: Maps, Objects
The word extend extends an object! or map! value 
with a list of key and value pairs. The first argument is modified.

The first argument must be object! or map!.
The second argument must be block!, hash! or map!

Refinements:
/case - use case-sensitive comparison
Examples
red>> users: make map! ["John23" "safe3" "DingSnooker" "mypasswd"]
== #(
"John23" "safe3"
"DingSnooker" "mypasswd"
)
; Create a map of 2 users and their passwords.

red>> more-users: make map! ["Jane" "pass123" "Sue" "secret"]
== #(
"Jane" "pass123"
"Sue" "secret"
)
; Create another map!

red>> extend users more-users
== #(
"John23" "safe3"
"DingSnooker" "mypasswd"
"Jane"... ;truncated output at the console
; Extend the first map! with the second.

red>> print users
"John23" "safe3"
"DingSnooker" "mypasswd"
"Jane" "pass123"
"Sue" "secret"
; Show all the users in the first map!

red>> extend users make map! ["JOHN23" "newPassword"]
== #(
"John23" "newPassword"
"DingSnooker" "mypasswd"
...
; Modify an existing map!

red>> print users
"John23" "newPassword"
"DingSnooker" "mypasswd"
"Jane" "pass123"
"Sue" "secret"
; Note: new password for John23 (case-insensitive)

top alphanumeric-index category-index



external!          type:  typeset!--    Cats: Datatypes
EXTERNAL! is a typeset! value: make typeset! [event!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



extract          type:  function!--    Cats: Series, String manipulation
The word extract extracts a value from a series! at 
regular intervals, returning a new series!.

Arguments are:
1. a series!
2. a skip size of type integer!.

Refinements:
/index - extract from an offset position (integer!).
/into - we provide an output series! instead
of creating a new one.
The results will be appended to the series!.
Examples
red>> extract [1 2 3 4 5 6 7] 3
== [1 4 7]
; Extracts every 3rd element of a block!.

red>> extract "abcdefghij" 2
== "acegi"
; Extracts every 2nd element of a string!.

red>> extract/index "abcdefghij" 2 4
== "dfhj"
; Start from an offset position (position = 4 at char! #"d")

red>> buffer: []
== []
; Create an empty buffer for results.

red>> extract/into [1 2 3 4 5 6 7] 2 buffer
== [1 3 5 7]

red>> extract/into [10 20 30 40 50 60] 2 buffer
== [1 3 5 7 10 30 50]

red>> buffer
== [1 3 5 7 10 30 50]
; The accumulated results in the buffer.

top alphanumeric-index category-index



extract-boot-args          type:  function!--    Cats: System Related
To do by red-by-example team ...


top alphanumeric-index category-index



face?          type:  function!--    Cats: GUI: VID, View, Type Checking
USAGE:
FACE? value

DESCRIPTION:
Returns TRUE if the value is a face! object.
FACE? is a function! value.

ARGUMENTS:
value "Value to test."

RETURNS:
[logic!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



false          type:  logic!--    Cats: Boolean, Constants
The word false represents the boolean value false. 
Is of datatype logic!
Examples
1 = 2
== false

top alphanumeric-index category-index



fetch-help          type:  function!--    Cats: Documentation, Help & Debug
docstart
USAGE:
FETCH-HELP 'word

DESCRIPTION:
Returns information about functions, values, objects, and datatypes.
FETCH-HELP is a function! value.

ARGUMENTS:
'word [any-type!]
.docend

Fetch-help is similar to help (or ?), but it allows the capturing of the information.
A string is returned.

If the word is not found, a "No matching..." string is returned.

Examples
;-- Example:  ask the user for a word, display its information
;-- note the to word! use.

the-word: ask "Type the word: "
word-info: fetch-help (to word! the-word )
print word-info

top alphanumeric-index category-index



fifth          type:  function!--    Cats: Series, String manipulation
The word fifth returns the fifth value in a series!. 

The argument can be one of:
series! tuple!

If there is no fifth item, then none is returned.
Examples
red>> fifth [1 2 3 4 5 6 7]
== 5

red>> fifth "ABCDEFG"
== #"E"

red>> fifth 12.16.13.15.22
== 22

red>> fifth [1 2 3]
== none
; No fifth element found

top alphanumeric-index category-index



file!          type:  datatype!--    Cats: Datatypes, Files
The word file! is a datatype!; it can be a: 
file name
directory name
directory path!.

A file! is a type of series!, rather like a string.
Note that this type is concerned with file names and places, rather than the contents of a file.

Here are some file! examples
%file.txt
%directory/
%directory/my%20stuff/file.txt
%"directory/my stuff/file.txt"
%/c/windows/softwaredistribution

Notes:
- a file! literal must always start with a percent sign %
- use forward slashes / (Unix style); back slashes will be automagically converted to /

Unusual characters in file names must be encoded with a % hexadecimal number,
such as %20 for space. Thus, my%20stuff refers to "my stuff"; alternatively,
we may enclose them in "quotes", and Red generates the hexadecimal codes for us.
Examples
; -------------------------------------------------------------------------
; The file! as a series!
; -------------------------------------------------------------------------

red>> find %top/work/red/demo.txt "red"
== %red/demo.txt

; -------------------------------------------------------------------------
; Use a file! to manipulate contents: load, save
; -------------------------------------------------------------------------

red>> save %demo.txt "some data for a file"

red>> print load %demo.txt
some data for a file

top alphanumeric-index category-index



file?          type:  function!--    Cats: Files, Type Checking
The word file? returns true if its argument is a file!.  

In Red, a file! type value is preceded by %.
If spaces are needed in a file name, enclose it in quotes or use hex %20, as in:
%"my files/"
%/my%20files/

In Windows the drive letter is part of the path!, like so:
%/c/windows/system32/xyz.dll

Absolute path!s start with %/ and relative path!s just with %.
Examples
red>> my-data: %/top/personal/stuff.txt
== %/top/personal/stuff.txt
; Absolute path

red>> file? my-data
== true

red>> file? %work.doc
== true
; Relative path

red>> file? %/folder1/folder2/
== true
; A path can also be a directory



top alphanumeric-index category-index



find          type:  action!--    Cats: Series, String manipulation
The word find returns the series! from the position where a value 
is found, or none.

Arguments:
1. the item to be searched can be:
series! bitset! typeset! any-object! map! none!
2. the value to be found can be any-type!

Refinements
/part - limit length of search to a length or to a position in the series.
The argument must be number! or series!
/only - Treat a series search value as a single value
/case - Perform a case-sensitive search.
/same - Use "same?" as comparator.
/any - Use * and ? wildcards in string searches. (Not available yet)
/with - Use custom wildcards in place of * and ?. (Not available yet)
/skip - Treat the series as fixed size records. Supply a size integer!
/last - Find the last occurrence of value, from the tail.
/reverse - Find the last occurrence of value, from the current index.
/tail - Return the tail of the match found, rather than the head.
/match - Match at current index only and return tail of match.
Examples
; -------------------------------------------------------------------------
; Simple finds - string, block, series, returns the series from the found point
; -------------------------------------------------------------------------

red>> find "The catfish" "cat"
== "catfish"

red>> find "The catfish" "CAT" ; find is case-insensitive by default
== "catfish"

red>> find "The catfish" "dog" ; returns none if not found
== none

red>> find [11 22 33 44 55 66] [ 33 44]
== [33 44 55 66]

; -------------------------------------------------------------------------
; The /part refinement with a length = limit on the region where the search takes place
; -------------------------------------------------------------------------

red>> find/part "The dog" "The" 2 ; search region restricted to "Th"
== none

red>> find/part "The dog" "he" 3 ; search region restricted to "The"
== "he dog"

red>> s: [1 2 3 4 5 6 7 ]
== [1 2 3 4 5 6 7]

red>> place: find s 3 ; find "3" in series "s"
== [3 4 5 6 7]

red>> index? place
== 3

red>> find/part s 2 place ; search restriced to pos 1 up to index? place
== [2 3 4 5 6 7]

red>> find/part s 4 place ; 4 is beyond the index of place
== none

; -------------------------------------------------------------------------
; The /only refinement (not valid for strings)
; -------------------------------------------------------------------------

red>> s: [11 22 [33 44] 55 66]
== [11 22 [33 44] 55 66]

red>> find/only s [33 44] ; treat the nested block as one item
== [[33 44] 55 66]

red>> find s [33 44] ; without /only we cannot find it
== none

; -------------------------------------------------------------------------
; The /skip refinement
; -------------------------------------------------------------------------

; In this cas FIND treats the series as a set of records, where each record
; has a fixed size. FIND will only try to match against each first item of such a record.

red>> s: [11 22 33 44 55 66]
== [11 22 33 44 55 66]

; Next examples have a record size of 2

red>> find/skip s 22 2 ; 22 is the second item of a record. So, no match
== none

red>> find/skip s 33 2 ; 33 is the first item of a record. So, a match
== [33 44 55 66]

; Next examples have a record size of 3

red>> find/skip s 22 3 ; 22 is the second item of a record. So, no match
== none

red>> find/skip s 33 3 ; 33 is the third item of a record. So, no match
== none

red>> find/skip s 44 3 ; 33 is the first item of a record. So, a match
== [44 55 66]

; -------------------------------------------------------------------------
; The /last refinement - search from the end, backwards
; -------------------------------------------------------------------------

red>> s: [11 22 33 44 33 22 11]
== [11 22 33 44 33 22 11]

red>> find/last s 22
== [22 11]

; -------------------------------------------------------------------------
; The /reverse refinement
; -------------------------------------------------------------------------

red>> s: "A1A2A3A4"
== "A1A2A3A4"

red>> s: at s 5 ; position the index halfway the string
== "A3A4"

red>> find/reverse s "A" ; searh backwards from current index
== "A2A3A4"

; -------------------------------------------------------------------------
; The /tail refinement
; -------------------------------------------------------------------------

; Normally FIND returns the result INCLUDING the matched item.
; With /TAIL the result returned is the part AFTER the matching search argument.

red>> find/tail "ABCDEF" "BC"
== "DEF" ; result does NOT include the search argument

red>> find "ABCDEF" "BC"
== "BCDEF" ; result DOES include the search argument

; -------------------------------------------------------------------------
; The /match refinement
; -------------------------------------------------------------------------

; Match always tries to match against the beginning of the series.
; Also the result is EXCLUSIVE the search argument.

red>> find/match "ABCDE" "A" ; mact, because "A" found at begin of string
== "BCDE"

red>> find/match "ABCDE" "D" ; no match - "D" not at beginning of string
== none

red>> find/match "ABCDE" "AB" ; match - search argument is at start of string
== "CDE"

red>> find/match "ABCDE" "DE" ; no match - search argument is beyond start of string
== none

top alphanumeric-index category-index



find-flag?          type:  routine!--    Cats: Type Checking
USAGE:
FIND-FLAG? facet flag

DESCRIPTION:
Checks a flag in a face object.
FIND-FLAG? is a routine! value.

ARGUMENTS:
facet [any-type!]
flag [word!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



first          type:  function!--    Cats: Series, String manipulation
The word first returns the first value in a series!. 

The argument can be one of:
series! tuple! pair!

If there is no first item, none is returned.
Examples
red>> first [3 4 5]
== 3
; First of a block!.

red>> first "ABC"
== #"A"
; First of a string!.

red>> first []
== none
; There is no first value here.

red>> first 22.33.44
== 22
; First of a tuple!.

red>> first 200x400
== 200
; First of a pair!.

top alphanumeric-index category-index



flip-exe-flag          type:  function!--    Cats: System Related
USAGE:
FLIP-EXE-FLAG path

DESCRIPTION:
Flip the sub-system for the red.exe between console and GUI modes (Windows only).
FLIP-EXE-FLAG is a function! value.

ARGUMENTS:
path [file!] "Path to the red.exe."
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



float!          type:  datatype!--    Cats: Datatypes, Math
The datatype! float! represents a number! type containing 
IEEE-754 64-bit floating point numbers.

In literals the e-notation can be used.

Floats that cannot be represented are NaN (Not a Number).
Examples
; -------------------------------------------------------------------------
; Some examples
; -------------------------------------------------------------------------

red>> 3e2
== 300.0

red>> 3.5 / 2.1
== 1.666666666666667

red>> 4 / 2.0
== 2.0

red>> 3e2 + 1
== 301.0

red>> 1.0 / 0
*** Math error: attempt to divide by zero
*** Where: /

top alphanumeric-index category-index



float?          type:  function!--    Cats: Type Checking
The word float? returns true if its argument is a float! type, 
otherwise false.
Examples
red>> float? 1.23
== true

red>> float? 3
== false
; No decimal point

red>> float? 3.0
== true

red>> float? "3"
== false
; Is a string


top alphanumeric-index category-index



forall          type:  native!--    Cats: Iteration
The word forall evaluates its body, moving through the 
provided series! one position at a time.

Note that it does not use a single value from the series! for each
repetition, as foreach does. Instead, it increments the index position
of the series!.
Examples
numbers: [1 2 -4 8 -16]

forall numbers [
print numbers
]
1 2 -4 8 -16
2 -4 8 -16
-4 8 -16
8 -16
-16

forall numbers [
if (first numbers) >= 0 [
print first numbers
]
]
1
2
8

top alphanumeric-index category-index



foreach          type:  native!--    Cats: Iteration
The word foreach evaluates its body (a block!) for each value in a series!.

A variable (or block! of variables) must be provided, and foreach will take
each value in the series! as the iteration proceeds.

The arguments are:
1. a variable or block! of variables.
2. a series!, e.g. block!, vector!, string! etc
3. a block! - the body, executed for each iteration
Examples
foreach country ["China" "Vietnam"  "Thailand"] [
print country
]
China
Vietnam
Thailand
; Assigns the values in the block in turn to the variable "country"

country-series: ["China" "Vietnam" "Thailand"]
foreach country country-series [
print country
]
China
Vietnam
Thailand
; Instead of using a literal block, you can also use a variable holding a block.

foreach character "Red" [
print character
]
R
e
d
; Prints in turn each cgaracter of the string specified.

capital-series: ["China" "Beijing" "USA" "Washington" "UK" "London"]
foreach [country city] capital-series [
prin country
prin " - capital is - "
print city
]
China - capital is - Beijing
USA - capital is - Washington
UK - capital is - London
; The prin function prints without outputting a newline.

top alphanumeric-index category-index



forever          type:  native!--    Cats: Iteration
The word forever evaluates a block! body repeatedly (= forever).
The word break can be used to exit the loop if required.
Examples
forever [
r: random 10
print r
if r > 5 [break]
]
3
7
; This ends when r gets a value higher than 5

forever [
print "hi"
]
"hi"
; The line above will be printed eternally ...

top alphanumeric-index category-index



form          type:  action!--    Cats: Conversion, Formatting
The form word converts a value to a string!, in a user-friendly format.

NOTE that, depending on the type, the resulting text might not contain extra
type information (such as [ ] { } and "") as would be produced by mold.

It has one argument, a value.

Refinements:
/part - an integer! value limiting the length of the result string!
Examples
Because the Red console has an effect on formatting, we will use print.

red>> print form "ABCDEFG"
ABCDEFG

red>> print form/part "ABCDEFG" 2
AB

red>> print form #"Z"
Z

red>> print form {The Great
Wall Of
China}
The Great
Wall Of
China

red>> print form [1 2 3 4 5 6]
1 2 3 4 5 6

red>> print form/part [1 2 3 4 5 6] 4
1 2

top alphanumeric-index category-index



fourth          type:  function!--    Cats: Series, String manipulation
The word fourth returns the fourth value in a series!. 

The argument can be one of:
series! tuple!

If there is no fourth item, none is returned.
Examples
red>> fourth [1 2 3 4 5 6 7]
== 4

red>> fourth "ABCDEFG"
== #"D"

red>> fourth [1 2 3]
== none
; No fourth value found!

red>> fourth 22.33.1.255
== 255

top alphanumeric-index category-index



func          type:  native!--    Cats: Functions
The word func is used to create functions.  

Items (variables etc) referred to in the body of a func are assumed to be global.

Se also: function.

Arguments:
1. block! of:
- function arguments
- refinements
- local variable definitions
2. the function body, a block!
Examples
; Using a global variable
add-up: func[a b] [
number: a + b
print number ; Global
]
number: 0 ; Global
add-up 3 5
print number ; Global
8 ; Global
8 ; Global

; Shadowing a global variable
add-up2: func [a b /local number] [
number: a + b
print number ; Local
]
number: 20 ; Global
add-up2 3 5
print number ; Global
8 ; Local
20 ; Local

; Using a refinement without a value
add-up3: func [a b /neg /local temp] [
temp: a + b
; Note that a refinement is a boolean
if neg [
temp: temp * -1
]
print temp
]
add-up3 3 5
8
add-up3/neg 3 5
-8

; Using a refinement with a value
add-up4: func [a b /c cval /local temp] [
temp: a + b
if c [
temp: temp + cval
]
print temp
]
add-up4 3 5
8
add-up4/c 3 5 6
14

top alphanumeric-index category-index



function          type:  native!--    Cats: Functions
The word function is used to define functions. 

Functions can accept arguments and return a result.

The general pattern of defining a function is:
my-function-name: function [spec] [
body i.e. code
]

In the spec part the following can be present:

- definition of arguments in the form:
name [type1 type2 ...]

- definition a possible return types:
return: [type1 type2 ...]

- /local followed by all variables that should be local to the
function
See note below.


- /extern followed by all variables that should not be defined as
local. This means that these variables should be
available in global scope. See note below.

Variables assigned using `set-word!` syntax (e.g. v: 123) in the body of
a function are automatically local to the function. If `set` is used instead,
the variable is NOT captured. The combination of those behaviours,
and the `/local` and `/extern` refinements, let you specify variable
locality that makes the intent clear in a variety of situations.

Function with `set-word!` usage is the most common case, and will
be most familiar if you're coming to Red from another language.

If we try to pass wrong types to a function, a run-time message
occurs during interpretation, or at execution time if we compiled it; the
lack of a compilation error message concerning invalid argument types
is due to the flexible way that Red handles types.

Returning from a function:

- exit - return without avalue

- return - return with a value
Examples
; -------------------------------------------------------------------------
; Shadowing a global variable
; -------------------------------------------------------------------------

add-up2: function [a b ] [
number: a + b ;set-word syntax here, so local
print number ; Local
]

number: 20 ; Global

red>> add-up2 3 5
8 ; Local

red>> print number
20 ; Global

; -------------------------------------------------------------------------
; Specify the type of the arguments
; -------------------------------------------------------------------------

show-bigger: function [
a[integer!]
b[integer!]
][
either a > b [
print a
][
print b
]
]

red>> show-bigger 44 55
55

red>> show-bigger 4 + 5 10
10

red>> show-bigger 4
*** Script error: show-bigger is missing its b argument
*** Where: show-bigger

red>> show-bigger "x" "y"
*** Script error: show-bigger does not allow string! for its a argument
*** Where: show-bigger

; -------------------------------------------------------------------------
; Allow multiple types for an argument - Generic functions
; -------------------------------------------------------------------------

show-bigger: function [
a[integer! float!]
b[integer! float!]
]

; -------------------------------------------------------------------------
; Or use a type that has other types as its subclasses
; -------------------------------------------------------------------------

show-bigger: function [
a[number!]
b[number!]
]

; -------------------------------------------------------------------------
; Returning a value from a function by default
; -------------------------------------------------------------------------

a-result: function[][
39
40 + 2 ; Last expression in a function is the return value
]

red>> print a-result
42

; -------------------------------------------------------------------------
; Returning a value from a function using return
; -------------------------------------------------------------------------

a-result: function[][
39
return 40 + 2
]

red>> print a-result
42

; -------------------------------------------------------------------------
; Using the returned value in an expression
; -------------------------------------------------------------------------

bigger: function [
a[number!]
b[number!]
][
either a > b [
a
][
b
]
]

red>> 2 + bigger 3 4
6

; -------------------------------------------------------------------------
; Sometimes we need parenthesis when calling a function
; -------------------------------------------------------------------------

red>> bigger (bigger 3 4) (bigger 5 6)
6

; -------------------------------------------------------------------------
; But most of the time it works without parenthesis
; -------------------------------------------------------------------------

red>> bigger bigger 4 5 6
6

; -------------------------------------------------------------------------
; Pass by value / by reference
; -------------------------------------------------------------------------


; When we pass scalar types (i.e. single items, such as a number!,
; a char!, a pair!) as arguments, a copy of their value is passed
; to the function!.

; When we pass a series! a reference is passed instead. The reason is
; that series! can be quite large; copying them would cost too much.

; Passing by reference makes it possible to change the series! from
; within a function!.

; Here an example - the series! will be changed in global scope!

my-append: function [data-block [block!] ][
append data-block -999
]

red>> numbers: [45 33 87 55]
== [45 33 87 55]

red>> my-append numbers
== [45 33 87 55 -999]

red>> numbers
== [45 33 87 55 -999]

; -------------------------------------------------------------------------
; A series! local to a function! - closing over a series!
; -------------------------------------------------------------------------


; A local series! when instantiated from a series! without
; copying, will keep its value over function calls!
; Note that this also applies to string!s

x-s: function[] [
xblock: [] ; The [] is modified each time calling the function!
append xblock "X"
print mold xblock
]

red>> x-s
["X"]

red>> x-s
["X" "X"]

red>> x-s
["X" "X" "X"]

; -------------------------------------------------------------------------
; Avoid the previous situation by copying the series! to initialize it
; -------------------------------------------------------------------------

x-s: function[] [
xblock: copy [] ; On each call we get a fresh new block!
append xblock "X"
print mold xblock
]

red>> x-s
["X"]

red>> x-s
["X"]

red>> x-s
["X"]

; -------------------------------------------------------------------------
; Comments in function! definitions
; -------------------------------------------------------------------------

bigger: function [
"return the bigger of 2 numbers"
arg1[number!] "first number argument"
arg2[number!] "second number argument"
][
either arg1 > arg2 [
arg1
][
arg2
]
]

red>> help bigger
USAGE:
bigger arg1 arg2
DESCRIPTION:
return the bigger of 2 numbers. ; Our docstring
bigger is of type: function!
ARGUMENTS:
arg1 [number!] => first number argument.
arg2 [number!] => second number argument.
REFINEMENTS:

; -------------------------------------------------------------------------
; Using refinements as options
; -------------------------------------------------------------------------

red>> a: [1 9 3 8 2 7 5 4 6]
== [1 9 3 8 2 7 5 4 6]

red>> sort a ; No refinement
== [1 2 3 4 5 6 7 8 9]

red>> a ; Note that sort changes the series!
== [1 2 3 4 5 6 7 8 9]

red>> sort/reverse a ; With /reverse refinement
== [9 8 7 6 5 4 3 2 1]

; -------------------------------------------------------------------------
; Using refinements needing an extra argument
; -------------------------------------------------------------------------

red>> sort/part a 4 ; /part refinement needs an extra argument
== [6 7 8 9 5 4 3 2 1]

red>> sort/reverse/part a 4 ; Combining these 2 refinements
== [9 8 7 6 5 4 3 2 1]

; -------------------------------------------------------------------------
; Using the /neg refinement as an option
; -------------------------------------------------------------------------

add-up3: function [a b /neg] [
temp: a + b
; Note that a refinement is a boolean
if neg [
temp: temp * -1
]
return temp
]

red>> add-up3 3 5
8

red>> add-up3/neg 3 5
-8

; -------------------------------------------------------------------------
; Using refinements /c and /d with extra arguments
; -------------------------------------------------------------------------

add-up4: function [a b /c cval /d dval] [
temp: a + b
; Note that a refinement is a boolean
if c [
temp: temp + cval
]
if d [
temp: temp - dval
]
return temp
]

red>> add-up4 3 5
== 8

red>> add-up4/c 3 5 3
== 11

red>> add-up4/d 3 5 3
== 5

red>> add-up4/c/d 3 5 4 5 ; Note that /c = 4 and /d = 5
== 7

red>> add-up4/d/c 3 5 4 5 ; Note that /c = 5 and /d = 4
== 9

; -------------------------------------------------------------------------
; Forward referencing a function!
; -------------------------------------------------------------------------


; By default you should define your function!s at the top of your
; program and call them later on.

; However, this is not required if and only if the call is from within
; another function!

show-all: function [] [
print "Powers of ten:"
display-powers ; Works from inside a function! body
]

display-powers: function[] [
print [10 1000 10000 100000]
]

red>> show-all
Powers of ten:
10 1000 10000 100000

; -------------------------------------------------------------------------
; Assigning functions to variables - use a prefix colon
; -------------------------------------------------------------------------

red>> sorteren: :sort
== make action! [[
{Sorts a series (modified); default sort or...

red>> sorteren [2 5 3 1 4]
== [1 2 3 4 5]

red>> sorteren/reverse [2 5 3 1 4]
== [5 4 3 2 1]

; -------------------------------------------------------------------------
; Returning from a function without a result value
; -------------------------------------------------------------------------


void: function [] [
exit
]

red>> mold void
== "unset"

; -------------------------------------------------------------------------
; Returning a result value
; -------------------------------------------------------------------------


val: function [] [
return "My message"
]

red>> val
== "My message"

; -------------------------------------------------------------------------
; The /extern refinement
; -------------------------------------------------------------------------


test: function [
/extern var1
] [
var1: 11
var2: 22
]

red>> var1: 1
== 1

red>> var2: 2
== 2

red>> test
== 22

red>> var1
== 11 ; Changed because of /extern - global scope

red>> var2
== 2 ; Shadowed - global scope not changed

top alphanumeric-index category-index



function!          type:  datatype!--    Cats: Datatypes, Functions
See function?

top alphanumeric-index category-index



function?          type:  function!--    Cats: Type Checking
The word function? returns true if its argument is a function, 
otherwise false.

The single argument can be of any type.
Examples
; -------------------------------------------------------------------------
; Make a function, try it, use function?
; -------------------------------------------------------------------------

red>> f: function [] [print "in function"]
== func [][print "in function"]

red>> f
in function ; The function works

red>> function? :f ; The colon is needed to prevent execution
== true ; Definitely a function

red>> function? f ; Is the return value of the function call a function?
in function
== false

red>> f2: func [] [func [] [print "Hi!"]]
== func [][func [] [print "Hi!"]]

red>> function? :f2 ; F2 itself is a function
== true

red>> function? f2 ; Executing F2 also returns a function
== true

red>> function? :first ; Is FIRST a function?
== true

red>> a: 3
== 3

red>> function? a ; Is A a function?
== false

top alphanumeric-index category-index



get          type:  native!--    Cats: Word Manipulation
The word get returns the value a word refers to.  
Use in to get a word value inside an object!

Arguments
The single argument is a word! or a path!.

Refinements
/any - If word has no value, return UNSET rather than causing an error.
/case - Use case-sensitive comparison (path only).
Examples
; -------------------------------------------------------------------------
; Using a word (w) with get
; -------------------------------------------------------------------------

red>> w: 123
== 123

red>> get 'w ; Use ' (quote) to prevent evaluation of w
== 123

red>> get first [w] ; Use [ ] to prevent evaluation of w
== 123

red>> get w ; w does not contain the name of an existing variable
*** Script Error: get does not allow integer! for its word argument
*** Where: get

; -------------------------------------------------------------------------
; Using a word (w) with get which contains a variable name
; -------------------------------------------------------------------------

red>> x: 12
== 12

red>> w: 'x
== x

red>> get w
== 12

; -------------------------------------------------------------------------
; Using get with a path
; -------------------------------------------------------------------------

red>> b: [11 22 33 44 55]
== [11 22 33 44 55]

red>> place: 3
== 3

red>> get first [b/:place]
== 33

red>> get 'b/:place
== 33

; -------------------------------------------------------------------------
; Using get indirect with a path
; -------------------------------------------------------------------------

red>> x: 12
== 12

red>> b: [11 22 x 44 55]
== [11 22 x 44 55]

red>> get first [b/:place]
== x

red>> get 'b/:place
== x

red>> get get first [b/:place]
== 12

red>> get get 'b/:place
== 12

top alphanumeric-index category-index



get-current-dir          type:  routine!--    Cats: Directories, Files
The word get-current-dir returns the current directory the program is using.  

When a program begins executing, its current directory is set to the one it is
stored in, but the current directory can be changed during run time.
Examples
; The example program is filefolders.exe, stored in this file structure:
; C:\red\file-dir-tests\
; filefolders.exe
; folder1A\
; folder1B\
; folder1C\

print ["Current-dir:" get-current-dir]
Current-dir: C:\red\file-dir-tests

cd %folder1A
print ["Current-dir:" get-current-dir]
Current-dir: C:\red\file-dir-tests\folder1A

cd %..
print "Current-dir: "print get-current-dir
Current-dir: C:\red\file-dir-tests


top alphanumeric-index category-index



get-env          type:  native!--    Cats: System Related
word get-env returns the value of an OS environment variable of the
current process, as a string1.

To get all environment variables/values, use list-env.

Arguments
The single argument can be any string or any word.
NOTE: the case of the argument is not relevant!
Examples
; -------------------------------------------------------------------------
; Get the value of the "USERPROFILE" environment variable
; -------------------------------------------------------------------------

red>> get-env "USERPROFILE" ; On Windows here
== "C:\Users\Mike"

top alphanumeric-index category-index



get-path!          type:  datatype!--    Cats: Datatypes
A get-path! is a kind of path! used to access (get) a value.  
Refer to path! and get-word! for more details.

To be completed by Red-by-example team.

Examples
; -------------------------------------------------------------------------
; Explore a get-path!
; -------------------------------------------------------------------------

red>> b: [11 22 33 44]

;with a variable
red>> place: 2
== 2
;use a get-path! Note preceding colon
red>> :b/:place
== 22
;Find the type - first [block] is used to prevent evaluation
red>> type? first [:b/:place]
== get-path!

top alphanumeric-index category-index



get-path?          type:  function!--    Cats: Type Checking
The word get-path? returns true if its argument is a get-path!,
otherwise false.

Its single argument can be any type.
Examples
; -------------------------------------------------------------------------
; Use get-path? on various types; must start with colon :
; -------------------------------------------------------------------------

red>> b: [11 22 33]
== [11 22 33]

red>> n: 2
== 2

red>> get-path? b/n
== false

red>> get-path? first [:b/:n]
== true

red>> get-path? first [b/n]
== false

top alphanumeric-index category-index



get-word!          type:  datatype!--    Cats: Datatypes
The datatype! get-word! is the way in which Red gets values from a variable.

The get-word! type gets the value of a word (which is quite normal thus
far) but does not evaluate the value. For that we use a colon in front of
a variable.

For many simple data types, the result is the value. For special datatype!s
like functions, we need to use the get-word notation.
Examples
; -------------------------------------------------------------------------
; Use get-word! type
; -------------------------------------------------------------------------

red>> w: 123
== 123

red>> w
== 123

red>> :w
== 123 ; For normal variable same as evaluating it

red>> f: func [] [print "Hi!"]
== func [][print "Hi!"]

red>> f ; Evaluate the function
Hi!

red>> :f ; Use the get-word - retrieve the definition of f
== func [][print "Hi!"]

top alphanumeric-index category-index



get-word?          type:  function!--    Cats: Type Checking
Returns true if its argument is a get-word! type, otherwise false.

Its single argument can be of any type.

Examples
; -------------------------------------------------------------------------
; A few types of argument
; -------------------------------------------------------------------------

red>> a-word: 123

;just a normal word
red>> get-word? a-word
== false
: :a-word syntax is correct, but word is evaluated
red>> get-word? :a-word
== false

;prevent evaluation, with first and a [block]
red>> get-word? first[:a-word]
== true

;this is a set-word!
red>> get-word? first[a-word:]
== false

top alphanumeric-index category-index



greater-or-equal?          type:  native!--    Cats: Comparison
The word greater-or-equal? is the functional form of the >=
infix word.
Examples
red>> greater-or-equal? 44 33
== true

top alphanumeric-index category-index



greater?          type:  native!--    Cats: Comparison
The word greater? is the functional form of the > infix word.
Examples
red>> greater? 44 33
== true

top alphanumeric-index category-index



halt          type:  function!--    Cats: Exiting, System Related
The halt word stops the interpretation of a script immediately.

Always returns a value of 1.
Examples
fun1: func [p1] [
fun2 p1
print "fun2 completed"
]

fun2: func [p2] [
print "Before halt check ..."
if p2 = "halt" [halt]
print "After halt check"
]

fun1 "abc"
Before halt check ...
After halt check
fun2 completed

fun1 "halt"
Before halt check ...

top alphanumeric-index category-index



has          type:  native!--    Cats: Functions
The word has is a way to define a function that does have local variables 
but has no arguments.

It is followed by a block! of local variable names, and a block! of code.
Examples
calc-hours: has  [number] [
number: 365 * 24 ; number is local
print number
]
calc-hours
8760

top alphanumeric-index category-index



hash!          type:  datatype!--    Cats: Datatypes
The datatype! hash! provides a block-like interface but with fast 
lookups for most values (block series can be stored in hash! too, but they
will not be hashed, so no faster access).

It is a very flexible container for any kind of hashed tables (not only
associative arrays) while keeping the handy navigational abilities of blocks.

A hash might save time with large data sets and repeated searching.

See also0 the datatype! map!.
Examples
; -------------------------------------------------------------------------
; Create a hash!, and use it
; -------------------------------------------------------------------------

red>> list: make hash! [a 123 "hello" b c 789]
== make hash! [a 123 "hello" b c 789]

red>> list/c
== 789

red>> find list 'b
== make hash! [b c 789]

red>> dict: make hash! [a 123 b 456 c 789]
== make hash! [a 123 b 456 c 789]

red>> select dict 'c
== 789

; -------------------------------------------------------------------------
; Regard DICT as 2 records of size 3 and find value 456
; -------------------------------------------------------------------------

red>> select/skip dict 456 3
== 123

top alphanumeric-index category-index



hash?          type:  function!--    Cats: Type Checking
Returns true if its argument is a hash! type, otherwise false.

Arguments

One argument, of any type.

Examples
; -------------------------------------------------------------------------
; hash? with a hash! and a block!
; -------------------------------------------------------------------------

red>> list: make hash! [a 123 "hello" b c 789]
;yes, a hash!
red>> hash? list
== true

;b is a block
red>> b: [1 2 3 4]
== [1 2 3 4]
red>> hash? b
== false

top alphanumeric-index category-index



head          type:  action!--    Cats: Series, String manipulation
The word head resets the index of a series! to its start.

Note that you can use the word head? to test if a series! is at position 1.

Note that you can use the word index? to obtain the current index.

Examples
red>> x: [1 2 3 4 5 6 7]
== [1 2 3 4 5 6 7]

red>> index? x
== 1

red>> head? x
== true

red>> x: skip x 3
== [4 5 6 7]

red>> index? x
== 4

red>> head? x
== false

red>> x: head x
== [1 2 3 4 5 6 7]

red>> index? x
== 1

red>> head? x
== true

top alphanumeric-index category-index



head?          type:  action!--    Cats: Series, String manipulation
The word head? checks whether a series! index is at the head
position (= position 1) and returns true if it is at head or false
otherwise.

Note that you can use the word index? to obtain the current index!
Examples
red>> x: [1 2 3]
== [1 2 3]

red>> head? x
== true

red>> index? x
== 1

red>> x: next x
== [2 3]

red>> head? x
== false

red>> index? x
== 2

top alphanumeric-index category-index



help          type:  function!--    Cats: Documentation, Help & Debug
The help word provides an overview of Red words and datatypes.
You may also type ? instead of help.

Help has 1 argument:
- a Red word!:
in this case help displays the help info for exactly that word!
- or a string!:
in this case help displays every piece of help info where this
string! occurs.
Examples
red>> help add
USAGE:
add value1 value2

DESCRIPTION:
Returns the sum of the two values.
add is of type: action!

ARGUMENTS:
value1 [number! char! pair! tuple! vector!]
value2 [number! char! pair! tuple! vector!]

REFINEMENTS:

red>> help *
USAGE:
value1 * value2

DESCRIPTION:
Returns the product of two values.
* is of type: op!

ARGUMENTS:
value1 [number! char! pair! tuple! vector!]
value2 [number! char! pair! tuple! vector!]

REFINEMENTS:

red>> help native!
all => Evaluates, returning at the first that is not true
any => Evaluates, returning at the first that is true
arccosine => Returns the trigonometric arccosine (in degrees by default)
arcsine => Returns the trigonometric arcsine (in degrees by default)
arctangent => Returns the trigonometric arctangent (in degrees by default)
... rest of output omitted here ...

red>> help "contr"
continue => Throws control back to top of loop
throw => Throws control back to a previous catch

red>> help "sine"
acos => Returns the trigonometric arccosine
arccosine => Returns the trigonometric arccosine (in degrees by default)
arcsine => Returns the trigonometric arcsine (in degrees by default)
asin => Returns the trigonometric arcsine
cos => Returns the trigonometric cosine
cosine => Returns the trigonometric cosine
sin => Returns the trigonometric sine
sine => Returns the trigonometric sine

top alphanumeric-index category-index



help-string          type:  function!--    Cats: Documentation, Help & Debug
docstart
USAGE:
HELP-STRING 'word

DESCRIPTION:
Returns information about functions, values, objects, and datatypes.
HELP-STRING is a function! value.

ARGUMENTS:
'word [any-type!]
.docend

Returns a string containing the spec. See also help, fetch-help.

If the word is not found, a "No matching..." string is returned.

Examples
;-- Example:  ask the user for a word, display its information
;-- note the to word! use.

the-word: ask "Type the word: "
word-info: help-string (to word! the-word )
print word-info

top alphanumeric-index category-index



hex-to-rgb          type:  function!--    Cats: Conversion, Colors
USAGE:
HEX-TO-RGB hex

DESCRIPTION:
Converts a color in hex format to a tuple value; returns NONE if it fails.
HEX-TO-RGB is a function! value.

ARGUMENTS:
hex [issue!] "Accepts #rgb, #rrggbb, #rrggbbaa."

RETURNS:
[tuple! none!]

; -------------------------------------------------------------------------
; hex-to-rgb
; -------------------------------------------------------------------------

>> hex-to-rgb #ff0000
== 255.0.0


top alphanumeric-index category-index



if          type:  native!--    Cats: Conditional branching
The word if evaluates a conditional expression. 
If the result thereof is true, the block! will be evaluated.
If false nothing happens.

Has 2 parameters:
1. a conditional expression
2. a block!.

If returns the resulting value of the block! if the condition is true and
else returns none.

Warning:
The if word is a pitfall for Red n00bs, because it doesn't have an else block!.
The either word provides what programmers would expect.
Examples
if 3 > 2 [print "3 > 2"]
3 > 2

if 3 > 2 [print "3 > 2"] [print "2 > 3"]
3 > 2
== [print "2 > 3"]
; This is a n00b error.
; The last block is not a part of the if, so the block is evaluated
; as a stand-alone block, which returns the block itself!

if 2 = 2.0 [print "Different datatypes, but still equal!"]
Different datatypes, but still equal!

if 2 == 2.0 [print "Different datatypes NOT equal!"]
none

top alphanumeric-index category-index



immediate!          type:  typeset!--    Cats: Type Checking
IMMEDIATE! is a typeset! value: make typeset! [datatype! none! logic! char!
integer! float! word! set-word! lit-word! get-word! refinement! issue!
typeset! pair! percent! tuple! time! handle! date!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



immediate?          type:  function!--    Cats: Type Checking
USAGE:
IMMEDIATE? value

DESCRIPTION:
Returns true if the value is any type of immediate.
IMMEDIATE? is a function! value.

ARGUMENTS:
value [any-type!]

; -------------------------------------------------------------------------
; immediate?
; -------------------------------------------------------------------------

>> immediate? 234
== true
>> immediate? [123]
== false
>> immediate? "23"
== false
>> immediate? #"2"
== true

top alphanumeric-index category-index



in          type:  native!--    Cats: Objects
The word in fetches a word from an object.

2 arguments:
1. an object! to be accessed
2. the word to be fetched - a word!, block!, or paren!
Examples
; -------------------------------------------------------------------------
; Use in on a-point
; -------------------------------------------------------------------------

red>> a-point: make object! [xval: 10 yval: 20]
== make object! [
xval: 10
yval: 20
]

red>> in a-point 'xval
== xval ; Existing member of object

red>> in a-point 'xxval
== none ; Not existing member of object%

red>> get in a-point 'xval
== 10 ; Value of member

top alphanumeric-index category-index



index?          type:  action!--    Cats: Series, String manipulation
The word index? returns the current index of a series! relative to the head, 
or of a word in a context.

The argument can be:
series! word!

In Red, the name referring to a series! need not indicate the first item.
It can be moved to index any part of a series.
It is not like an array name in traditional languages.

NOTE: when you assign a variable to a series, that variable points to the same
series! as the one it is assigned to. This can cause big trouble!!!!
Normally always use copy to avoid that.
Examples
; Create a series
red>> numbers: [2 4 8 3 9 27]
== [2 4 8 3 9 27]

; Are we at the start of "numbers"? (index starts at 1, not zero)
red>> index? numbers
== 1

; Find returns the part of the series! from the found item's position
; or none if not found
red>> n: find numbers 9
== [9 27]

; "n" is also a series!
red>> n
== [9 27]

; But "n" still refers to the series! called "numbers"
red>> index? n
== 5

; We could write this more concisely
red>> index? find numbers 9
== 5

; Show that "n" is just a "pointer" into "numbers"
; The "head"of "n" is the same as the "head" of "numbers"
; because the underlaying series! is exactly the same!
red>> n: head n
== [2 4 8 3 9 27]

; NOTE: beware that directly assigning to a series! can wreak havoc!
red>> s1: [1 2 3 4]
== [1 2 3 4]
red>> s2: next s1
== [2 3 4]
red>> append s2 5
== [1 2 3 4 5]
; Append always returns the whole series! and does not consider the index
red>> s2
== [2 3 4 5]
; "s2" is modified
red>> s1
= [1 2 3 4 5]
; "s1" also modified!

; NOTE: avoid this "problem" by using copy
red>> s1: [1 2 3 4]
== [1 2 3 4]
red>> s2: copy next s1
== [2 3 4]
red>> append s2 5
== [2 3 4 5]
red>> s2
== [2 3 4 5]
; "s2"is modified
red>> s1
== [1 2 3 4]
; But "s1" is left intact!

top alphanumeric-index category-index



input          type:  function!--    Cats: Input
Gets the value that the user types at STDIN.
INPUT is a function! value.
Has 0 parameters.

It is identical to ask with no parameters.

The resulting string value can be used in an expression
Examples
my-name: input    ;-- I type    Mike   now:
Mike
== "Mike"

top alphanumeric-index category-index



insert          type:  action!--    Cats: Series, String manipulation
The word insert inserts (a) value(s) at a series! index.  

The original series! is modified and insert returns the part of the series!
from the position following the insert.

The 2 arguments are:
1. a series! i.e series! bitset! map!
2. a value, which can be of any type

Refinements:
/part - Limit the number of values inserted.
We provide a length of type: number!
or a "pointer" of type series!
/only - insert block! types as single values (overrides /part).
Normally each value in a block! would be separately inserted.
/dup - Duplicate the inserted values. Must provide a count of type number!

NOTE: insert is a destructive operation! It alters its argument.
Most of the time you need to copy before using insert!
Examples
red>> s: "this is a string"
== "this is a string"

; Insert at current index - which is 1.
red>> insert s "I think "
== "this is a string"
red>> s
== "I think this is a string"

; Insert at other positions (e.g. after "d")
red>> letters: "abcdefg"
== "abcdefg"
red>> insert find letters "d" "XX"
== "defg"
; This result is the result of "find", not of "insert"!
red>> letters
== "abcXXdefg"
; Now you see the result of "insert".

; Insert at the tail
red>> insert tail letters "-END-"
== ""
; Again: this is the result of "find".
red>> letters
== "abcXXdefg-END-"
; And this of "insert".

; Insert a duplicate, 5 times
red>> insert/dup s "-" 5
== "I think this is a string"
red>> s
== "-----I think this is a string"

; Make a string for /part
red>> s2: "YES it is"
== "YES it is"
; Only insert the first 6 characters of "s2" into "s".
red>> insert/part s s2 6
== "-----I think this is a string"
red>> s
== "YES it-----I think this is a string"

; We need a block type to illustrate /only.
red>> a-block: [3 4 5]
== [3 4 5]
; Normal insert, without /only.
red>> insert a-block [33 44 55]
== [3 4 5]
; Note the separate items.
red>> a-block
== [33 44 55 3 4 5]

; Reset the block.
red>> a-block: [3 4 5]
== [3 4 5]
; Now use /only
red>> insert/only a-block [33 44 55]
== [3 4 5]
; Now the block is inserted, instead of its elements.
red>> a-block
== [[33 44 55] 3 4 5]

top alphanumeric-index category-index



integer!          type:  datatype!--    Cats: Datatypes, Math
The datatype! integer! represents a number! type containing 
32 bit whole signed numbers.
Examples
; -------------------------------------------------------------------------
; Some examples
; -------------------------------------------------------------------------

red>> 33 + 55
== 88

red>> 6 / 7
== 0 ; Dividing 2 integers gives rounded result

red>> 6.0 / 7
== 0.8571428571428571

red>> add 6 7
== 13

top alphanumeric-index category-index



integer?          type:  function!--    Cats: Type Checking
The word integer? returns true if its argument is an integer! type, 
otherwise false.

Its argument can be any type.
Examples
; A literal integer value
red>> integer? 123
== true

; A variable holding an integer value
red>> a: 456
== 456

red>> integer? a
== true

red>> integer? 22x30
== false

red>> integer? 12.3
== false

top alphanumeric-index category-index



internal!          type:  typeset!--    Cats: Datatypes
INTERNAL! is a typeset! value: make typeset! [unset!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



intersect          type:  native!--    Cats: Sets
The word intersect returns the intersection (the common items) of two sets. 

The arguments can be sets of:
block! hash! string! bitset! typeset!

To create a set with no duplicate items, the unique function can be used.

Refinements:
/case - use case-sensitive comparison.
/skip - treat the series! as fixed size records.
The specified size is an integer!.
Examples
; Create 2 series
red>> list1: ["India" "China" "Vietnam" "Singapore"]
== ["India" "China" "Vietnam" "Singapore"]

red>> list2: ["uk" "china" "USA" "India" "France"]
== ["uk" "china" "USA" "India" "France"]

; Common values in these sets
red>> intersect list1 list2
== ["India" "China"]

; When case sensitive
red>> intersect/case list1 list2
== ["India"]

top alphanumeric-index category-index



issue!          type:  datatype!--    Cats: Datatypes
The issue! datatype! can be used to represent values such as product 
codes, credit-card numbers etc. Greater-than/less than comparisons are
allowed.

Literal values in a program must begin with #, and end with a space.
Examples:

#AB-999
#+00-1254-776534
#driver:2019,May
#My-tag

; -------------------------------------------------------------------------
; Issue examples
; -------------------------------------------------------------------------

>> a: #AB-999
== #AB-999
>> b: #BB-999
== #BB-999
>> b > a ;-- compare 2 issues
== true
>> to issue! "My-tag" ;-- make an issue from a string
== #My-tag

top alphanumeric-index category-index



issue?          type:  function!--    Cats: Type Checking
USAGE:
ISSUE? value

DESCRIPTION:
Returns true if the value is this type.
ISSUE? is a function! value.

ARGUMENTS:
value [any-type!]

See issue!

top alphanumeric-index category-index



keys-of          type:  function!--    Cats: Functions, Reflection
Theword keys-of returns the list of words of a value that supports reflection. 

Arguments
One argument, which should support reflection, e.g. map!, object!.
Examples
; -------------------------------------------------------------------------
; Extract the keys of an object
; -------------------------------------------------------------------------

red>> a-point: make object! [
[ xval: 10
[ yval: 20
[ ]
== make object! [
xval: 10
yval: 20
]

red>> keys-of a-point
== [xval yval]

; -------------------------------------------------------------------------
; Extract the keys of a map
; -------------------------------------------------------------------------

red>> a-map: make map![height 6.1 weight 250 age 45]
== #(
height: 6.1
weight: 250
age: 45
)

red>> keys-of a-map
== [height weight age]

top alphanumeric-index category-index



last          type:  function!--    Cats: Series, String manipulation
The word last returns the last value in a series!.  
If the series! is empty, none is returned.

Its single argument is a series!.
Note that a string! is a series of char!.
Examples
red>> last ["cat" "dog" "bird"]
== "bird"

red>> last [33 44]
== 44

red>> last []
== none

red>> last "abcd"
== #"d"


top alphanumeric-index category-index



last-lf?          type:  routine!--    Cats: Input, Output
To do by red-by-example team ...


top alphanumeric-index category-index



length?          type:  action!--    Cats: Series, String manipulation
The word length? returns the number of values in a series!, 
from the current index to the tail.

The length of an empty series! is 0.

The length of none is none.

Its single argument can be one of these types:
series! bitset! map! tuple! none
Examples
red>> length? [10 20 30]
== 3

red>> length? []
== 0

; Tuple
red>> length? 22.33.44.100
== 4

; Find returns the series from the found item (30) onwards,
; which is [30 40 50]
red>> length? find [10 20 30 40 50] 30
== 3

red>> length? none
== none

; Find returns none; then length is none.
red>> length? find [10 20 30 40 50] 123
== none

top alphanumeric-index category-index



lesser-or-equal?          type:  native!--    Cats: Comparison
The word lesser-or-equal? returns true if the first argument
is less than or equal to the second argument, otherwise false.

It is the functional equivalent of the infix word <=.
Examples
red>> lesser-or-equal? 33 44
== true

red>> "ABC" <= "abc"
== true

red>> "abc" <= "ABC"
== true

red>> [4 8 5] <= [4 2 1]
== false

red>> [4 1 1] <= [4 2 1]
== true

top alphanumeric-index category-index



lesser?          type:  native!--    Cats: Comparison
The word lesser? returns true if the first argumjent is 
less than the second argument, otherwise false.

It is the functional equivalent of the infix word <.
Examples
red>> lesser? 33 44
== true

red>> lesser? [8 5 2] [ 7 5 2]
== false

red>> lesser? [6 5 2] [ 7 5 2]
== true

top alphanumeric-index category-index



lf          type:  char!--    Cats: Constants
A pre-defined char! value.

See char!

top alphanumeric-index category-index



list-dir          type:  function!--    Cats: Directories, Files
The word list-dir shows a list of all files and directories within the
directory given as its argument.

Refinements:
/col - displays in n columns instead of the default 4
Examples
; -------------------------------------------------------------------------
; Show contents of current directory
; -------------------------------------------------------------------------

red>> list-dir %/e/src
8th/ go/ python/ red/
spiderbasic/

red>> list-dir/col %/e/src 3
8th/ go/ python/
red/ spiderbasic/
red>> list-dir/col %/e/src 2
8th/ go/
python/ red/
spiderbasic/

top alphanumeric-index category-index



list-env          type:  native!--    Cats: System Related
The word list-env returns a map! of OS environment variables/values
of the current process.

No arguments.

To get the value of a specific variable, use get-env.
Examples
; -------------------------------------------------------------------------
; Use list-env on a Windows PC
; -------------------------------------------------------------------------

red>> type? list-env
== map!

red>> list-env
== #(
"=::" "::\"
"=E:" "E:\Websites\Red-by-Example\auto-v5"
"ALLUSERSPROFILE" "C:\ProgramData"
"APPDATA" "C:\Users\xapwi\AppData\Roaming"
"CommonP... ; The three dots indicate that more ouput is skipped

red>> print list-env ; Prints all the output
... ; Output suppressed - too big

top alphanumeric-index category-index



lit-path!          type:  datatype!--    Cats: Datatypes
Look in the official VID documents:
https://doc.red-lang.org/en/vid.html
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



lit-path?          type:  function!--    Cats: Type Checking
USAGE:
LIT-PATH? value

DESCRIPTION:
Returns true if the value is this type.
LIT-PATH? is a function! value.

ARGUMENTS:
value [any-type!]
; -------------------------------------------------------------------------
; lit-path
; -------------------------------------------------------------------------

>> p: 'a/b/c ;-- a lit-path
== a/b/c ;-- evaluates to a path
>> type? p
== path!
>> p: first ['a/b/c] ;-- no evaluation
== 'a/b/c
>> type? p
== lit-path!

top alphanumeric-index category-index



lit-word!          type:  datatype!--    Cats: Datatypes
The datatype! lit-word! is needed to get the literal value (the name) 
of a word.

To get the lit-word of variable w, we use 'w.
Examples
; -------------------------------------------------------------------------
; Use a lit-word type
; -------------------------------------------------------------------------

red>> a-word: 123
== 123

red>> a-word
== 123

red>> 'a-word
== a-word

top alphanumeric-index category-index



lit-word?          type:  function!--    Cats: Type Checking
Returns true if its argument is a lit-word! type, otherwise false.

Its single argument can be of any type.

Examples
; -------------------------------------------------------------------------
; A few types of argument
; -------------------------------------------------------------------------


red>> a-word: 123

red>> lit-word? a-word
== false

;correct lit-word syntax, but we should not evaluate it
red>> lit-word? 'a-word
== false

;prevent evaluation with first [block]
red>> lit-word? first ['a-word]
== true

top alphanumeric-index category-index



ll          type:  function!--    Cats: Directories, Files
To do by red-by-example team ...


top alphanumeric-index category-index



load          type:  function!--    Cats: Files, Input
The word load returns a value or block! of values from a file. 

Text files and certain types of binary files can be handled.

Its argument specifies the path! to the data and can be:
file! url! string! binary!

Refinements:
/part - load a part of the data, where the part length is
integer! or string!
/into - put results into an existing block!, instead
of creating a new block!.
We need then to provide a block! to be used.
/as - specify the type of the data to be loaded;
we need to specify either:
- none -> load data as code
- word! -> e.g. json, html, jpeg, png, etc.
/header - include Red header as a loaded value
/all - does not evaluate Red header
Examples
; one-number.txt has one number in it.
red>> load %one-number.txt
== 234

; This file has 3 numbers, one per line.
; For more than 1 item, a block will be created.
red>> load %three-numbers.txt
== [234 567 789]

; Store the result of load.
red>> some-numbers: load %three-numbers.txt
== [234 567 789]

red>> some-numbers
== [234 567 789]

red>> genres: load %music-types.txt
== ["Blues" "Rock" "Jazz"]

; It is easy to put program code in a file
; and load it ...
red>> prog: load %code-type.txt
== [print "Hello from a block of code in a file!"]

; Use do to execute the result of a load.
red>> do prog
Hello from a block of code in a file!

; face.jpg contains an image, 216 x 216 pixels.
; (the console truncates long values to ... )
red>> p: load %face.jpg
== make image! [216x216 #{
AFB3B6AFB3B6AFB3B6AFB3B6AEB2B5AEB2B5AEB...

top alphanumeric-index category-index



load-thru          type:  function!--    Cats: Files, Input, URL/Internet
USAGE:
LOAD-THRU url

DESCRIPTION:
Loads a remote file through local disk cache.
LOAD-THRU is a function! value.

ARGUMENTS:
url [url!] "Remote file address."

REFINEMENTS:
/update => Force a cache update.
/as => Specify the type of data; use NONE to load as code.
type [word! none!] "E.g. bmp, gif, jpeg, png."
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



log-10          type:  native!--    Cats: Math
The word log-10 returns the logarithm (base 10) of its argument.

The argument can be a number! (a float! or an integer! )
Examples
red>> log-10 9.9
== 0.99563519459755

red>> log-10 1000
== 3.0

top alphanumeric-index category-index



log-2          type:  native!--    Cats: Math
The word log-2 returns the logarithm (base 2) of its argument.

The argument can be a number! (a float! or an integer!)
Examples
red>> log-2 2.1
== 1.070389327891398

red>> log-2 32
== 5.0

top alphanumeric-index category-index



log-e          type:  native!--    Cats: Math
The word log-e returns the natural (base E) logarithm of its argument.

The argument can be a number! (a float! or an integer!)
Examples
red>> log-e 2.7
== 0.9932517730102835

red>> log-e 3
== 1.09861228866811

top alphanumeric-index category-index



logic!          type:  datatype!--    Cats: Datatypes, Logic
The datatype! logic! consists of two states representing 
true and false.

They are returned from comparisons using > <= etc.

The provided boolean words and their values are:

- the pair:
true = true
false = false

- the pair:
on = true
off = false

- the pair:
yes = true
no = false

Note that on and off and yes and no have no built-in logic.
They are preset words which can be more meaningful in certain situations.
.pre
red>> 3 > 2
== true

red>> a: 3
== 3

red>> answer: a > 2
== true

red>> answer
== true

red>> not answer
== false

red>> if a > 2 [print "bigger"]
bigger

red>> yes
== true

; Note: we get false, not no
red>> not yes
== false

red>> power-switch: off
== false

red>> if power-switch = off [power-switch: on]
== true

; Note, not on but true.
red>> power-switch
== true

top alphanumeric-index category-index



logic?          type:  function!--    Cats: Type Checking
The word logic? returns true if its argument is of 
the logic! datatype!, otherwise false.

its argument can be on any type.
Examples
red>> open: true
== true

red>> logic? open
== true

red>> large: false
== false

; It is true that 'false' is a logic! type.
red>> logic? large
== true

; Expressions resulting in a logic! result
red>> logic? 3 > 2
== true

red>> logic? 3 + 2
== false

; yes, no, on and off are also logic!
red>> logic? yes
== true

red>> logic? no
== true

red>> logic? on
== true

red>> logic? off
== true

top alphanumeric-index category-index



loop          type:  native!--    Cats: Iteration
The word loop executes a given block! a given number of times.

Has 2 parameters:
1. a number! (number of times to evaluate the block!)
2. a block! (to be evaluated the specified number of times)

loop has no return value.
Examples
loop 3 [print "Hi!"]
Hi!
Hi!
Hi!

i: 0
loop 10 [i: i + 1]
print ["Value of i =" i]
Value of i = 10

top alphanumeric-index category-index



lowercase          type:  native!--    Cats: String manipulation
The word lowercase converts a string of characters to lower-case. 

The single argument can be a string! or a char!.

Refinements:
/part - limits to a given length or position.

NOTE: this is a destructive operation. When applying it to a variable,
the variable will be changed!

See also uppercase.
Examples
; -------------------------------------------------------------------------
; Try lowercase on char and string
; -------------------------------------------------------------------------

red>> lowercase #"A"
== #"a"

red>> lowercase "ABCD EFGH ijk"
== "abcd efgh ijk"

; -------------------------------------------------------------------------
; Use /part to specify first 2 chars only
; -------------------------------------------------------------------------

red>> lowercase/part "ABCD EFGH ijk" 2
== "abCD EFGH ijk"

top alphanumeric-index category-index



ls          type:  function!--    
This word is a synonym for list-dir
top alphanumeric-index category-index


make          type:  action!--    Cats: Create, Datatypes
The word make returns a new value, based on a type and a specification for the type.

It has 2 arguments:
1. the datatype!, an example or a prototype value
2. the specification of the new value or the number of items (for vector!).

The actual detail of these arguments depends on the datatype!.

For series! types, the specification is often a value for the initial size
of the series!.
Examples
red>> make block! 10   ;; size 10 initially
== []

red>> make [] 3
== []

red>> make vector! [1 5 3]
== make vector! [1 5 3]

red>> make vector! 6
== make vector! [0 0 0 0 0 0]

v: make vector! 0
== make vector! []

top alphanumeric-index category-index



make-dir          type:  function!--    Cats: Files
The word make-dir creates a directory.  

Returns no error if the directory already exists; the contents of existing
directories will be preserved.

The single argument is a file!.

Refinements
/deep - create subdirectories as well
Examples
; -------------------------------------------------------------------------
; Make directory in the directory that the interpreter was run from
; -------------------------------------------------------------------------

red>> make-dir %make2/
== %make2/

; -------------------------------------------------------------------------
; The /deep refinement - new directory make3, and its sub-dir
; -------------------------------------------------------------------------

red>> make-dir/deep %make3/sub-dir/
== %make3/sub-dir/

top alphanumeric-index category-index



map!          type:  datatype!--    Cats: Datatypes
The datatype! map! represents a series! type.

This datatype provides a dictionary-like data structure, to make it
easy to store key/value pairs while providing very fast lookups.

Note that a map! is NOT a series!, so does not have the
concept of offset or positions.

A map! can have a wide range of types for its keys and values.

Entering a map! in literal format:
#(key1: val1 key2: val2 ... key3: val3)

Note that select and put are case-insensitive about keys.
To make them case-sensitive, use the case refinement, as in select/case.
.pre
; -------------------------------------------------------------------------
; Create 2 users with their respective passwords in a map!
; -------------------------------------------------------------------------

red>> users: make map! ["John23" "safe3" "DingSnooker" "mypasswd"]
== #(
"John23" "safe3"
"DingSnooker" "mypasswd"
)

red>> print users
"John23" "safe3"
"DingSnooker" "mypasswd"

; -------------------------------------------------------------------------
; Retrieve passwords
; -------------------------------------------------------------------------

red>> print select users "john23" ; Note: case insensitive!
safe3

red>> print select users "mr-x"
none ; Not found in the map!

; -------------------------------------------------------------------------
; Add a new user/password
; -------------------------------------------------------------------------

red>> put users "JaneUK" "magicpass"
== "magicpass"

red>> print users
"John23" "safe3"
"DingSnooker" "mypasswd"
"JaneUK" "magicpass"

; -------------------------------------------------------------------------
; Change a password for an existing user
; -------------------------------------------------------------------------

red>> put users "John23" "mygoodPass"
== "mygoodPass"

red>> print users
"John23" "mygoodPass"
"DingSnooker" "mypasswd"
"JaneUK" "magicpass"

; -------------------------------------------------------------------------
; Delete a user
; -------------------------------------------------------------------------

red>> put users "John23" none
== none

red>> print users
"DingSnooker" "mypasswd"
"JaneUK" "magicpass"

; -------------------------------------------------------------------------
; How many users left?
; -------------------------------------------------------------------------

red>> print length? users
2

; -------------------------------------------------------------------------
; Select a user by his key
; -------------------------------------------------------------------------

red>> users: make map! ["John23" "safe3" "DingSnooker" "mypasswd"]
== #(
"John23" "safe3"
"DingSnooker" "mypasswd"
)
red>> select users "John23"
== "safe3"

top alphanumeric-index category-index



map?          type:  function!--    Cats: Type Checking
The word map? returns true if its argument is a map! datatype!, 
otherwise false.

This datatype! provides a dictionary-like data structure,
storing key/value pairs.
Examples
; Using a map literal
red>> p: #(a: 3 b: 4 c: 5)
== #(
a: 3
b: 4
c: 5
)

; Use make to create a map
red>> users: make map! ["John23" "safe3" "DingSnooker" "mypasswd"]
== #(
"John23" "safe3"
"DingSnooker" "mypasswd"
)

red>> map? users
== true

red>> ages: [1 1949 2 1980 3 1999]
== [1 1949 2 1980 3 1999]

red>> map? ages
== false

; Extending a map with new keys/values:
red>> x: make map! [1 "January" 2 "Februari" 3 "March"]
== #(
1 "January"
2 "Februari"
3 "March"
)

red>> extend x [4 "April" 5 "May"]
== #(
1 "January"
2 "Februari"
3 "March"
4 "April"...

red>> print mold x
#(
1 "January"
2 "Februari"
3 "March"
4 "April"
5 "May"
)

; Retrieving a value using a key.
red>> x/1
== "January"

red>> x/5
== "May"

; Out of range
red>> x/7
== none

top alphanumeric-index category-index



math          type:  function!--    Cats: Math
This function evaluates a block! using mathematical precedence rules, 
returning the last result.

Arguments

The single argument is a block!.

Examples
. box Evaluate a block with math, then without.
>> a: 6
== 6
; Evaluate the / before the +
>> math [a + 8 / 2]
== 10

; Now left-to right, the + first
>> print [a + 8 / 2]
7

top alphanumeric-index category-index



max          type:  native!--    Cats: Math
The word max returns the greater of its 2 arguments. 

The 2 arguments must be of:
scalar! series!
Examples
red>> max 4 3
== 4

red>> max 3.1 3.11
== 3.11

red>> max #"B" #"C"
== #"C"

red>> max "ABC" "BBC"
== "BBC"

red>> max "ABC" "ABCD"
== "ABCD"

red>> max [1 2 3] [2 2 3 3]
== [2 2 3 3]


top alphanumeric-index category-index



min          type:  native!--    Cats: Math
The word min returns the smaller of its two arguments. 

There are 2 arguments of type:
scalar! series!
Examples
red>> min  4 3
== 3

red>> min 3.1 3
== 3

red>> min #"B" #"C"
== #"B"

red>> min "ABC" "BBC"
== "ABC"

red>> min "ABC" "ABCD"
== "ABC"

red>> min [1 2 3] [3 2 1 0]
== [1 2 3]

top alphanumeric-index category-index



mod          type:  function!--    Cats: Math
USAGE:
MOD a b

DESCRIPTION:
Compute a nonnegative remainder of A divided by B.
MOD is a function! value.

ARGUMENTS:
a [number! char! pair! tuple! vector! time!]
b [number! char! pair! tuple! vector! time!] "Must be nonzero."

RETURNS:
[number! char! pair! tuple! vector! time!]

See also modulo

; -------------------------------------------------------------------------
; mod
; -------------------------------------------------------------------------

>> mod 7 3 ;-- integer - divides 2 times
== 1
>> mod -7 3 ;-- negative - divides -3 times, mod must be non-negative
== 2
>> mod 7.5 2.1 ;-- float - divides 3 times
== 1.2

top alphanumeric-index category-index



modify          type:  action!--    Cats: Conversion
USAGE:
MODIFY target field value

DESCRIPTION:
Change mode for target aggregate value.
MODIFY is an action! value.

ARGUMENTS:
target [object! series!]
field [word!]
value [any-type!]

REFINEMENTS:
/case => Perform a case-sensitive lookup.

RETURNS:
[map! file!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



modulo          type:  function!--    Cats: Math
USAGE:
MODULO a b

DESCRIPTION:
Wrapper for MOD that handles errors like REMAINDER. Negligible values
(compared to A and B) are rounded to zero.
MODULO is a function! value.

ARGUMENTS:
a [number! char! pair! tuple! vector! time!]
b [number! char! pair! tuple! vector! time!]

RETURNS:
[number! char! pair! tuple! vector! time!]
See also mod
(Awaiting additional documentation by red-by-example team.)


top alphanumeric-index category-index



mold          type:  action!--    Cats: Formatting
The word mold returns a Red-readable string! representing a value.

This means that, for example, values can be stored in files and re-input to
a program when molded.

Type information is included in the string!for example:
[ ] around a block,
#"" around a character
and { } around multi-line strings

A single argument of any type is required

Refinements
/only - Exclude outer brackets if value is a block!
/all - Return value in loadable format
/flat - Exclude all indentation
/part - Limit the length of the result, where limit is an integer!
Examples
red>> print mold 12.34
12.34

red>> print mold "a string"
"a string"

red>> mold #"A"
#"A"

red>> print mold { The Great
Wall Of
China}
" The Great^/ Wall Of^/China"

red>> print mold [1 2 3]
[1 2 3]

red>> print mold/only [1 2 3]
1 2 3

red>> print mold/part [1 2 3 4 5] 3
[1

top alphanumeric-index category-index



move          type:  action!--    Cats: Series, String manipulation
Moves one or more elements from one series to another position or series. 
By default, one element is moved. The origin series is modified and
returned. The target series is modified.

Arguments

origin - a series!
target - a series!

Refinements
/part - control the number of values inserted. We supply an
integer! length.

Examples
; -------------------------------------------------------------------------
; move, and its effects
; -------------------------------------------------------------------------

;make 2 series
red>> s1: [a b c d]
red>> s2: [11 12]

;move first element of s1 to s2
;note the returned value: a modified s1
red>> move s1 s2
== [b c d]

;s1 is modified
red>> s1
== [b c d]

;s2 is modified
red>> s2
== [a 11 12]

; -------------------------------------------------------------------------
; /part refinement
; -------------------------------------------------------------------------

;make 2 series
red>> s1: [a b c d e]
red>> s2: [1 2 3 4]

;move 2 elements, not 1
red>> move/part s1 s2 2
== [c d]
red>> s2
== [a b 1 2 3 4]

top alphanumeric-index category-index



multiply          type:  action!--    Cats: Math
The word multiply multiplies 2 number!s.
This is equivalent to the infix operator *.

Has 2 arguments, which must be of type:
number! char! pair! tuple! vector!
Examples
red>> multiply 3 4.2
== 12.6

red>> multiply 11x20 4
== 44x80

red>> multiply 1.4.5 2
== 2.8.10

red>> v: make vector![2 3 4]
== make vector! [2 3 4]

red>> v2: make vector![20 20 3]
== make vector! [20 20 3]

red>> multiply v v2
== make vector! [40 60 12]

top alphanumeric-index category-index



NaN?          type:  native!--    Cats: Math
The word NaN? returns true if the argument is 'not a number',
otherwise false.

'Not a number' means that it is impossible to represent it internally.

The argument is of type: number!
Examples
; 1.5 is a valid number!
red>> NaN? 3 / 2
== false

; 3 is a valid number!
red>> NaN? square-root 9
== false

; Square root of a negative number.
red>> NaN? square-root -9
== true


top alphanumeric-index category-index



native!          type:  datatype!--    Cats: Datatypes
Represents external functions that are written in Red/System code, not in Red.

Type:
? native!
to get a list of them.

top alphanumeric-index category-index



native?          type:  function!--    Cats: Functions, Type Checking
USAGE:
NATIVE? value

DESCRIPTION:
Returns true if the value is this type.
NATIVE? is a function! value.

ARGUMENTS:
value [any-type!]
See native


top alphanumeric-index category-index



needs          type:  unset!--    Cats: Files, GUI: VID, View, Input
Used to incorporate modules of code into your program.

You will meet this early on when using VID,as in:

Red[ needs 'View]

...rest of program.


top alphanumeric-index category-index



negate          type:  action!--    Cats: Math
The word negate inverses its argument (positive <-> negative).
Examples
red>> negate 3
== -3

red>> negate -3
== 3

red>> negate 5x4
== -5x-4

red>> negate 5x-4
== -5x4

red>> negate -5x4
== 5x-4

top alphanumeric-index category-index



negative?          type:  native!--    Cats: Comparison
The word negative? returns true if the numeric parameter 
is less than zero, otherwise false.

NOTE that zero returns false.

Has one numeric parameter.
Examples
negative? -2
== true

negative? 0
== false

negative? 0.1
== false

top alphanumeric-index category-index



new-line          type:  native!--    Cats: Series
word new-line sets or clears the new-line markers within a block! or paren!.  
These markers are not considered when Red examines values, but do affect the displayed
format. The original series! is modified.

Arguments
1. position - a block! or paren!, positioned to the required place.
2. value - logic!. Use true/on/yes for newlines to be added.

Refinements
/all - set/clear marker to end of series.
/skip - set/clear marker periodically to the end of the series.
We must provide and integer! skip size.
Examples
; -------------------------------------------------------------------------
; Show that series can contain new-lines
; -------------------------------------------------------------------------

red>> b1: [1 2 3 4 5 6]
== [1 2 3 4 5 6] ; No new-lines here

red>> b2:[ 1 2 ; First new-line in series
[ 3 4 ; Second new-line in series
[ 5 6]
== [1 2
3 4
5 6
]

red>> b2
== [1 2
3 4
5 6
]

red>> b1 = b2
== true ; Equal despite new-lines difference

; -------------------------------------------------------------------------
; Manipulate series with new-lines
; -------------------------------------------------------------------------

red>> b: [1 2 3 4 5 6]
== [1 2 3 4 5 6]

red>> new-line next next b on
== [
3 4 5 6 ; Returns the series beginning with the new new-line
]
red>> b
== [1 2 ; Now the new-line becomes visible
3 4 5 6
]

; -------------------------------------------------------------------------
; The /all refinement
; -------------------------------------------------------------------------

red>> new-line/all b off
== [1 2 3 4 5 6] ; All new-lines removed

red>> new-line/all b on
== [ ; Now new-lines everywhere
1
2
3
4
5
6
]

red>> new-line/all b off
== [1 2 3 4 5 6] ; All new-lines removed

; -------------------------------------------------------------------------
; The /skip refinement
; -------------------------------------------------------------------------

red>> new-line/all/skip b on 2
== [
1 2
3 4
5 6
]

top alphanumeric-index category-index



new-line?          type:  native!--    Cats: Output, Type Checking
USAGE:
NEW-LINE? position

DESCRIPTION:
Returns the state of the new-line marker within a list series.
NEW-LINE? is a native! value.

ARGUMENTS:
position [any-list!] "Position to change marker."

RETURNS:
[any-list!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



newline          type:  char!--    Cats: Constants
A pre-defined char! value.

See char!

top alphanumeric-index category-index



next          type:  action!--    Cats: Series, String manipulation
The word next moves the index of a series! 1 position towards
the tail (= the end) of the series!.

When a series! index is already at tail position, next won't
change the index; it stays at tail.

The opposite of next is back.
Examples
red>> ser: [1 2 3]
== [1 2 3]

red>> ser: [1 2 3]
== [1 2 3]

red>> next ser
== [2 3]

red>> ser ; next is not destructive
== [1 2 3]

red>> ser: next ser
== [2 3]

red>> ser
== [2 3]

red>> ser: next ser
== [3]

red>> ser
== [3]

red>> ser: next ser
== [] ; We are at tail postion

red>> tail? ser
== true

red>> ser
== []

red>> ser: next ser ; Already at tail - do nothing
== []

red>> tail? ser
== true

red>> ser
== []

top alphanumeric-index category-index



no          type:  logic!--    Cats: Boolean, Constants
The value no can be used as the boolean value false.
Examples
red>> no
== false

red>> not no
== true

top alphanumeric-index category-index



none          type:  none!--    Cats: Boolean, Constants
The word none is a special value, and its datatype is none!

none is not the same as an empty block!, empty string!,
zero number! or null char!.

It is an actual value that represents non-existence.

none is returned in certain circumstances from several functions,
primarily those involving series!.
Examples
pick [11 22 33] 2
== 22
; Elements in a block are numbered 1 thru n

pick [11 22 33] 4
== none
; Out of range results in a none value

pick [true false true] 2
== false

pick [true false true] 4
== none
; Out of range results in a none value

a: 123
== 123

type? a
== integer!

a: none
== none
; none is just a value, like 123 before

type? a
== none!

either pick [11 22 33] 4 [print "got it"] [print "problem"]
problem
; In a comparison none behaves the same as false

some-function: func [arg1] [
; code omitted
return none ; no answer found
]
; This function returns none as the return value

answer: some-function 42
== none

print none? answer
true

top alphanumeric-index category-index



none!          type:  datatype!--    Cats: Datatypes
The none! datatype contains a single value that represents nothing or no 
value. See none for more details.




top alphanumeric-index category-index



none?          type:  function!--    Cats: Type Checking
The word none? returns true if its argument has a none value,
otherwise false.

Its single argument can be of any type.
Examples
red>> none? 3 / 4
== false

; Find searches and returns none if not found
red>> none? find "ABCD" "Z"
== true

; If found, returns the series! from the found item ("BCD").
red>> none? find "ABCD" "B"
== false

top alphanumeric-index category-index



normalize-dir          type:  function!--    Cats: Directories, Files
USAGE:
NORMALIZE-DIR dir

DESCRIPTION:
Returns an absolute directory spec.
NORMALIZE-DIR is a function! value.

ARGUMENTS:
dir [file! word! path!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



not          type:  native!--    Cats: Bit manipulation, Boolean, Comparison, Logic
The word not returns the logical complement of a value.

NOTE that only the logic! values false and none
return true.

For other types such as integer!, float!, bitset!,
false is returned, irrespective of the data value.

Use complement to perform a bitwise not.
Examples
red>> not (3 > 2)
== false

red>> not (10 > 20)
== true

red>> not 1
== false

red>> not 0
== false

red>> not -1
== false

red>> not none
== true

top alphanumeric-index category-index



not-equal?          type:  native!--    Cats: Comparison, Type Checking
The word not-equal? returns true if two values (of any type)
are not equal.

When comparing string!s lowercase is considered equal to uppercase.

There is also an infix <> operator, doing the same.
Examples
red>> not-equal? 12 12.0
== false

red>> not-equal? "abc" "abc"
== false

red>> not-equal? "abC" "ABC"
== false

top alphanumeric-index category-index



now          type:  native!--    Cats: Date/Time
The word now returns the current date and time.

Refinements allow the selection of, for example, only the date (as a date! type),
or only the time (as a time! type).

There are no arguments

Refinements
/year - Returns year only. integer!
/month - Returns month only. integer!
/day - Returns day of the month only. integer!
/time - Returns time only. time!
/zone - Returns time zone offset from UCT (GMT) only. time!
/date - Returns date only. date!
/weekday - Returns day of the week as integer! (Monday is day 1).
/yearday - Returns day of the year (Julian). integer!
/precise - High precision time. date!
/utc - Universal time (no zone). date!

Examples

; -------------------------------------------------------------------------
; No refinements (NB executed on 10 September 2017, in UK)
; -------------------------------------------------------------------------

>> d: now
== 10-Sep-2017/10:41:58+01:00
>> type? d
== date!
; -------------------------------------------------------------------------
; Some refinements
; -------------------------------------------------------------------------

>> now/time
== 10:42:57
>> now/year
== 2017
>> now/date
== 10-Sep-2017


top alphanumeric-index category-index



null          type:  char!--    Cats: Constants
A pre-defined char! value.

See char!

top alphanumeric-index category-index



number!          type:  typeset!--    Cats: Datatypes, Math
The datatype! number! is a typeset! containing other datatype!s.
Examples
; -------------------------------------------------------------------------
; Show all subtypes of number!
; -------------------------------------------------------------------------

red>> ? number!
number! is a typeset! of value:
make typeset! [
integer!
float!
percent!
]

top alphanumeric-index category-index



number?          type:  function!--    Cats: Type Checking
docstart
USAGE:
NUMBER? value

DESCRIPTION:
Returns true if the value is any type of number.
NUMBER? is a function! value.

ARGUMENTS:
value [any-type!]
.docend

Checks for a number! type. This is type-checking, not input validation.

Examples
>> number? "123"  ;-- a string
== false
>> number? 123 ;-- integer!
== true

>> f: 12.34
>> number? f ;-- float!
== true

>> number? 33% ;-- percent
== true


top alphanumeric-index category-index



object          type:  function!--    Cats: Objects
An object is a container that groups data and/or functions within 
one variable.

Red implements 'prototype-based objects'.

Creating new objects is done by cloning existing objects
or the base object! value.

During the creation process, existing field values can be modified
and new fields can be added.

It is a very simple and efficient model to encapsulate your Red code.
Examples
; make an object - a pretend square box
box: make object! [
size: 10
show: function [] [
print ["Showing size =" size "from within the box!"]
]
]

; Use the encapsulated function
box/show
Showing size = 10 from within the box!

top alphanumeric-index category-index



object!          type:  datatype!--    Cats: Datatypes
Object Model
------------
Red implements prototype-based objects. Creating new objects is done
by cloning existing objects or the base object! value. During the creation
process, existing field values can be modified and new fields can be added.
It is a very simple and efficient model to encapsulate your Red code.

Object Creation
---------------
We create new objects by:

make object! <specification block>

There are also some shorter alternative syntaxes (just handy shortcuts):

object <specification block>
context <specification block>

The specification block can contain any valid Red code. Words set at the root
level of that block will be collected and will constitute the new object's fields.

You can put any valid code into a specification block, and it will be evaluated
during the object construction, and only then. Here is an example. Note that
"hello" is printed when we make the object, but not when we evaluate it:

red>> obj: make object! [print "hello" a: 1 b: 2]
hello
== make object! [
a: 1
b: 2
]

;now use it
red>> obj
== make object! [
a: 1
b: 2
]


Nesting
-------
Objects can also be nested easily:
obj: object [
a: 123
b: object [
c: "hello"
d: object [
data: none
]
]
]

Another way to create an object is to use the copy action which does not
require a specification block, so does just a simple cloning of the object.
Existing functions will be re-bound to the new object.

Syntax:
copy <object>

Object Access Paths
-------------------

In order to access object fields, the common path syntax is used (words
separated by a slash character). Each word (or expression) in a path is
evaluated in the context given by the left side of the path. Evaluation
of a word referring to a function will result in invoking the function,
with its optional refinements.

Example:

book: object [
title: author: none
show: does [print [mold title "was written by" author]]
]

book/title: "The Time Machine"
book/author: "H.G.Wells"
print book/title
book/show

will output:

The Time Machine
"The Time Machine" was written by H.G.Wells

SELF Reference
--------------

A special keyword named self has been reserved when self-referencing
the object is required.

Example:

book: object [
title: author: none
list-fields: does [words-of self]
]
book/list-fields

will output:

[title author list-fields]


Object inheritance
------------------

Though cloning produces exact replicas of the prototype object, it is also
possible to extend it in the process, using make action.

Syntax:
make <prototype> <spec>

<prototype> : object that will be cloned and extended
<spec> : specification block

Example:
a: object [value: 123]

c: make a [
increment: does [value: value + 1]
]

print c/increment
print c/increment

will output:

124
125

It is also possible to use another object as <spec> argument. In such
case, both objects are merged to form a new one. The second object takes
priority in case both objects share same field names.

Example:
a: object [
value: 123
show: does [print value]
]
b: object [value: 99]

c: make a b
c/show

will output:

99


Extended Actions and Natives for Objects
----------------------------------------

You can use set on an object to set all fields at the same time, and
get on an object will return a block of all the fields values.

Example:

obj: object [a: 123 b: "hello"]
probe get obj
set obj none
?? obj
set obj [hello 0]
?? obj
probe :obj/a

will output:

[123 "hello"]
obj: make object! [
a: none
b: none
]
obj: make object! [
a: 'hello
b: 0
]
hello

The find function gives you a simple way to check for a field name in
an object. If found it will return true, else none.

The select action does the same check as find, but returns the field
value for matched word.
obj: object [a: 123]
probe find obj 'a
probe select obj 'a
probe find obj 'hello

will output:

true
123
none

The in word will allow you to bind a word to a target context:

a: 0
obj: object [a: 123]
probe a
probe get in obj 'a

will output:

0
123

The bind function is also available.

Reflectors
----------

The reflective functions words-of, values-of, body-of can be
used to access an object's internal structure.


These notes are heavily based on
http://www.red-lang.org/2014/12/050-objects-support.html








top alphanumeric-index category-index



object?          type:  function!--    Cats: Type Checking
The word object? returns true if its argument is an object!.

The single argument can be of any type.
Examples
; make an object - a pretend square box
red>> box: make object! [
[ size: 10
[ show: function [] [
[ print ["Showing size =" size "from within the box!"]
[ ]
[ ]
== make object! [
size: 10
show: func [][
print ["...

; Is this an object?
red>> object? box
== true

; Definitely not an object
red>> amounts: [2 3 4]
== [2 3 4]

red>> object? amounts
== false

top alphanumeric-index category-index



odd?          type:  action!--    Cats: Math
The word odd? returns true if its numeric parameter is odd,
else returns false.

Has 1 numeric parameter, which should be an integer!.
Examples
odd? -3
== true

odd? 10
== false

top alphanumeric-index category-index



off          type:  logic!--    Cats: Boolean
The word off has the logical value "false" 
and its datatype! is logic!

Logical values are produced from various comparisons.

The logic! type also provides:
false, no, on, true, yes
Examples
red>> ? off
off is a logic! of value: false

red>> either off [print "t is true"] [print "t is NOT true"]
t is NOT true

top alphanumeric-index category-index



offset?          type:  function!--    Cats: Series
USAGE:
OFFSET? series1 series2

DESCRIPTION:
Returns the offset between two series positions.
OFFSET? is a function! value.

ARGUMENTS:
series1 [series!]
series2 [series!]
; -------------------------------------------------------------------------
; offset?
; -------------------------------------------------------------------------

>> s: "the big cat" ;-- nb "c" is 9th char
== "the big cat"
>> s2: find s "cat"
== "cat"
>> offset? s s2
== 8

top alphanumeric-index category-index



on          type:  logic!--    Cats: Boolean, Constants
The word on has the logical value "true" 
and its datatype! is logic!

Logical values are produced from various comparisons.

The logic! type also provides:
false, no, off, true, yes
Examples
red>> ? on
on is a logic! of value: true

red>> either on [print "It is true!"] [print ["It is NOT true!"]]
It is true!

top alphanumeric-index category-index



on-face-deep-change*          type:  function!--    Cats: GUI: VID, View
USAGE:
ON-FACE-DEEP-CHANGE* owner word target action new index part state
forced?

DESCRIPTION:
Internal use only.
ON-FACE-DEEP-CHANGE* is a function! value.

ARGUMENTS:
owner
word
target
action
new
index
part
state
forced?
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



on-parse-event          type:  function!--    Cats: Parse
USAGE:
ON-PARSE-EVENT event match? rule input stack

DESCRIPTION:
Standard parse/trace callback used by PARSE-TRACE.
ON-PARSE-EVENT is a function! value.

ARGUMENTS:
event [word!] {Trace events: push, pop, fetch, match, iterate,
paren, end.}
match? [logic!] "Result of last matching operation."
rule [block!] "Current rule at current position."
input [series!] "Input series at next position to match."
stack [block!] "Internal parse rules stack."

RETURNS:
TRUE: continue parsing, FALSE: stop and exit parsing.
[logic!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



op!          type:  datatype!--    Cats: Datatypes
The datatype! op! represents the Red functions that act as infix 
operators.
Examples
; -------------------------------------------------------------------------
; List all infix operators with type op!
; -------------------------------------------------------------------------

red>> ? op!
% => Returns what is left over when one value is divided by another
* => Returns the product of two values
** => Returns a number raised to a given power (exponent)
+ => Returns the sum of the two values
- => Returns the difference between two values
/ => Returns the quotient of two values
// => Compute a nonnegative remainder of A divided by B
< => Returns TRUE if the first value is less than the second
<<
<= => Returns TRUE if the first value is less than or equal
to the second
<> => Returns TRUE if two values are not equal
= => Returns TRUE if two values are equal
== => Returns TRUE if two values are equal, and also the
same datatype
=? => Returns TRUE if two values have the same identity
> => Returns TRUE if the first value is greater than the second
>= => Returns TRUE if the first value is greater than or equal to
the second
>>
>>>
and => Returns the first value ANDed with the second
is => Defines a local reactive relations inside a reactor
or => Returns the first value ORed with the second
xor => Returns the first value exclusive ORed with the second

; -------------------------------------------------------------------------
; Some examples of infix operations
; -------------------------------------------------------------------------

red>> 1 + 2
== 3

red>> 2 * 5
== 10

red>> 10 / 2
== 5

red>> 10 // 2
== 0

red>> 10 // 3
== 1

top alphanumeric-index category-index



op?          type:  function!--    Cats: Type Checking
The word op? returns true if its argument is an op! type.  

This type includes infix operators, such as + - * etc).

Note the use of : to prevent evaluation of the argument!
Examples
red>> op? :and
== true

red>> op? :print
== false

red>> op? :+
== true

red>> op? :-
== true

red>> op? :float?
== false

top alphanumeric-index category-index



or          type:  op!--    Cats: Bit manipulation, Boolean, Comparison, Logic
The infix word or performs a logical "or" of two values.
The values are restricted to these types:
logic! integer! char! bitset! typeset!
pair! tuple! #vector!

It is the infix version of the word or~.

In the case of oring two integer!s (or closely related types,
such as char! and pair!), a bitwise (bit-by-bit) process is performed.

In general, types can be mixed, but logic! types cannot be mixed with other types.

The type of the result is the same type as the first value for a bitwise or.
For a logic! or, true or false are returned.
Examples
red>> (3 > 2) or false
== true

red>> 8 or 16
== 24

red>> 16 or false
*** Script error: logic type is not allowed here
*** Where: or

red>> my-pair: 3x4
== 3x4

red>> my-pair or 1
== 3x5

red>> 1 or my-pair
*** Script error: or does not allow pair for its value2 argument
*** Where: or

red>> v1: make vector![1 2 3]
== make vector! [1 2 3]

red>> v2: make vector![1 1 1]
== make vector! [1 1 1]

red>> v1 or v2
== make vector! [1 3 3]

top alphanumeric-index category-index



or~          type:  action!--    Cats: Bit manipulation, Boolean, Comparison, Logic
The or~ word performs a logical "or" of its 2 arguments.
The values are restricted to these types:
logic! integer! char! bitset! typeset! pair! tuple! vector!

It is the functional version of the infix word or.

In the case of or~ing two integer!s (or types closely related to integers,
such as char!, pair!), a bitwise (bit-by-bit) process is performed.

In general, types can be mixed, but logic! types cannot be mixed with other types.

The type of the result is the same type as the first value for a bitwise or~.
For a logic or~, true or false are returned.
Examples
red>> or~ (3 > 2) false
== true

red>> or~ 8 16
== 24

red>> or~ 16 false
*** Script error: logic type is not allowed here
*** Where: or~

red>> my-pair: 3x4
== 3x4

red>> or~ my-pair 1
== 3x5

red>> or~ 1 my-pair
*** Script error: or~ does not allow pair for its value2 argument
*** Where: or~

red>> v1: make vector![ 1 2 3]
== make vector! [1 2 3]

red>> v2: make vector![1 1 1]
== make vector! [1 1 1]

red>> or~ v1 v2
== make vector! [1 3 3]

top alphanumeric-index category-index



os-info          type:  routine!--    Cats: System Related
USAGE:
OS-INFO

DESCRIPTION:
Returns detailed operating system version information.
OS-INFO is a routine! value.
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



overlap?          type:  function!--    Cats: GUI: VID, View
USAGE:
OVERLAP? A B

DESCRIPTION:
Return TRUE if the two faces bounding boxes are overlapping.
OVERLAP? is a function! value.

ARGUMENTS:
A [object!] "First face."
B [object!] "Second face."

RETURNS:
TRUE if overlapping.
[logic!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



pad          type:  function!--    Cats: Formatting, String manipulation
The word pad pads a string! on the right side with spaces.

The arguments are:
1. the string! to pad
2. the total size (integer!) of the new string!.

Refinements:
/left - pads the string! at its left side.
Examples
; Note the 4 (i.e. 6 - 2) spaces between B and X
red>> prin "X" prin pad "AB" 6 print "X" print "-123456-"
XAB X
-123456-

; Note the 4 spaces between the X and A
red>> prin "X" prin pad/left "AB" 6 print "X" print "-123456-"
X ABX
-123456-

top alphanumeric-index category-index



pair!          type:  datatype!--    Cats: Datatypes
The datatype! pair! represents a scalar! type containing 
2 values.

A pair looks like:
axb

Pairs can be used to represent points in Cartesian space. (Coordinates)

The constituents of a pair! can be retrieved as follows:
- retrieve left value by either pairname/1 or pairname/x
- retrieve right value by either pairname/2 or pairname/y
Examples
; -------------------------------------------------------------------------
; Some examples
; -------------------------------------------------------------------------

red>> coord1: 10x20
== 10x20

red>> coord2: 100x100
== 100x100

red>> coord1 + coord2
== 110x120

red>> coord1 * coord2
== 1000x2000

red>> coord1/x
== 10

red>> coord1/1
== 10

red>> coord2/y: 234
== 234

red>> coord2
== 100x234

top alphanumeric-index category-index



pair?          type:  function!--    Cats: Type Checking
The word pair? returns true if its argument is of datatype! pair!.

The argument can be of any type.
; Integer
red>> pair? 123
== false

; Tuple
red>> pair? 1.2.33
== false

; Pair
red>> pair? 22x33
== true

; Result of adding 2 pairs
red>> pair? 22x33 + 1x1
== true


top alphanumeric-index category-index



paren!          type:  datatype!--    Cats: Datatypes
A paren! is a series! of items enclosed in parentheses ( ).  It is 
evaluated when it is encountered, and a result is returned.

In Red, infix operators have no priority, and paren! types can sometimes add
clarity.

Examples
; -------------------------------------------------------------------------
; Work with infix operators
; -------------------------------------------------------------------------

red>> (1 + 2)
== 3

red>> 3 + ((4 + 5) * (2 + 3))
== 48

; -------------------------------------------------------------------------
; Preventing evaluation with e.g. [ ]
; -------------------------------------------------------------------------

red>> first [(2 + 3)]
== (2 + 3)

;a paren! is a series!
red>> first first [(2 + 3)]
== 2

;here 2 + 3 is evaluated first, so first tries to work on 5
red>> first (2 + 3)
*** Script Error: first does not allow integer! for its s argument
*** Where: first

top alphanumeric-index category-index



paren?          type:  function!--    Cats: Type Checking
Returns true if its argument is a paren! type, otherwise false.

The single argument can be of any type.

Examples
; -------------------------------------------------------------------------
; Exercise paren?
; -------------------------------------------------------------------------

; The paren! is evaluated first. Paren? 3 is false
red>> paren? (1 + 2)
== false

; the paren! is evaluated first
red>> paren? [(1 + 2)]
== false

;'first fetches a paren!
red>> paren? first [(1 + 2)]
== true

top alphanumeric-index category-index



parse          type:  native!--    Cats: Parse
USAGE:
PARSE input rules

DESCRIPTION:
Process a series using dialected grammar rules.
PARSE is a native! value.

ARGUMENTS:
input [binary! any-block! any-string!]
rules [block!]

REFINEMENTS:
/case => Uses case-sensitive comparison.
/part => Limit to a length or position.
length [number! series!]
/trace =>
callback [function! [event [word!] match? [logic!]
rule [block!] input [series!] stack [block!] return: [logic!]]]

RETURNS:
[logic! block!]

See the Red-by-example notes,at:

http://www.red-by-example.org/parse.html


top alphanumeric-index category-index



parse-trace          type:  function!--    Cats: Parse
USAGE:
PARSE-TRACE input rules

DESCRIPTION:
Wrapper for parse/trace using the default event processor.
PARSE-TRACE is a function! value.

ARGUMENTS:
input [series!]
rules [block!]

REFINEMENTS:
/case => Uses case-sensitive comparison.
/part => Limit to a length or position.
limit [integer!]

RETURNS:
[logic! block!]

The same as parse but produces trace information.

See the Red-by-example notes,at:

http://www.red-by-example.org/parse.html



top alphanumeric-index category-index



path!          type:  datatype!--    Cats: Datatypes, Objects, Series
A path! is used to access items, often those contained in larger 
structures. The path! syntax is basically a series of items (including
paren!) separated by '/', and is applicable to a range of data types.
It might help your understanding if you look at the lower-level
get-word!, set-word! and lit-word! types first. Here are some
introductory examples of path!.
Examples
; -------------------------------------------------------------------------
; with series - string and block
; -------------------------------------------------------------------------


red>> str: "ABCDE"

;get element 3
red>> str/3
== #"C"

;get element 2. NB b/2, not b / 2, which divides.
red>> b: [11 22 33 44]
red>> b/2
== 22

;with a paren! in a path
red>> b/(1 + 2)
== 33

red>> n: 1
red>> b/(n + 1)
== 22

;here, b has a nested block at position 4
red>> b: [11 22 33 [444 555] 66]
;get element 4, position 1
red>> b/4/1
== 444

;now with words, not literal numbers
red>> x: 4
red>> y: 1

;get element with a get-path! Note preceding : (more on this below)
red>> b/:x/:y
== 444

;set elementwith a set-path! Note following : (more on this below)
red>> b/:x/:y: 1111
== 1111
;note the changed value
red>> b
== [11 22 33 [1111 555] 66]

;with symbols - here, the value AFTER the symbol is returned
red>> sales: [UK 10000 USA 15000 China 33000]
red>> sales/USA
== 15000

; -------------------------------------------------------------------------
; Path Examples With Refinement
; -------------------------------------------------------------------------


Many function words use 'refinements' to modify their action. Here is
sort with its reverse refinement:
red>> ages: [55 33 73 73 19]
red>> sort/reverse ages
== [73 73 55 33 19]

Using Paths - set/get/lit Paths
-------------------------------

When we use colons or ticks in a path, the type of the path becomes a
set-path!, a get-path!, or a lit-path. This is similar in
concept to get-word!, set-word! and lit-word!.

If we have a block such as:

b: [11 22 33 44]

then we can use numbers in a straightforward way, as in:

b/2 ; get element at position 2
b/2: 2222 ; set element at position 2

With words used as variables, we must use set-path! and get-path!
types, as in:

red>> b/:x/:y ;get-path! type

red>> b/:x/:y: 1111 'set-path! type


We can also use a lit-path! type, as in:

'b/x

which evaluates to

b/x


Paths As Series
---------------

A path is a series, and its elements can be accessed with the series! functions.

Here, the first [block] is used to prevent evaluation

red>> second first [the/white/cat]
== white

top alphanumeric-index category-index



path-thru          type:  function!--    Cats: Files, Input, URL/Internet
USAGE:
PATH-THRU url

DESCRIPTION:
Returns the local disk cache path of a remote file.
PATH-THRU is a function! value.

ARGUMENTS:
url [url!] "Remote file address."

RETURNS:
[file!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



path?          type:  function!--    Cats: Files, Objects, Series, Type Checking
The word path? returns true if its argument is a path! type.
Otherwise false.

Its single argument can be of any type.

There are several types of path! related words:
path! lit-path! set-path! get-path!

To test if an argument is any of these types, use any-path?.
To restrict the test to path! only, use path?

For more details on the ways of interpreting a word (involving ' and :),
the reader should look at the entries on lit-word! get-word! and set-word!
Examples
; -------------------------------------------------------------------------
; With a get-path! type - false
; -------------------------------------------------------------------------

red>> path? first [:a/b/c]
== false

; -------------------------------------------------------------------------
; With a path! - true
; -------------------------------------------------------------------------

red>> path? first [a/b/c]
== true

top alphanumeric-index category-index



percent!          type:  datatype!--    Cats: Datatypes
The datatype! percent! represents a number! type containing 
32 bit whole signed numbers.
Examples
; -------------------------------------------------------------------------
; Some examples
; -------------------------------------------------------------------------

red>> 35 * 10%
== 3.5

red>> 35 * (10.0 / 100) ; Exactly the same
== 3.5

red>> 100% / 40% ; Not so useful?
== 250%

top alphanumeric-index category-index



percent?          type:  function!--    Cats: Type Checking
The word percent? returns true if its argument is a percent! type, 
otherwise false.

The argument can be any type.
Examples
red>> x: 100%
== 100%

red>> percent? x
== true

red>> y: 200
== 200

red>> percent? y
== false

top alphanumeric-index category-index



pi          type:  float!--    Cats: Constants, Math
The word pi is a mathematical constant.

It can be roughly approached by dividing 22 by 7.
Examples
red>> ? pi
pi is a float! of value: 3.141592653589793

red>> 22.0 / 7
== 3.142857142857143

top alphanumeric-index category-index



pick          type:  action!--    Cats: Series, String manipulation
The word pick takes the nth value of a series!, where n is the second argument
Examples
; -------------------------------------------------------------------------
; Using a block! of numbers
; -------------------------------------------------------------------------

red>> x: [1 2 3 4 5 6 7 8]
== [1 2 3 4 5 6 7 8]

red>> y: pick x 4
== 4

red>> x
== [1 2 3 4 5 6 7 8]

red>> y
== 4

; -------------------------------------------------------------------------
; Using a string!
; -------------------------------------------------------------------------

red>> s: "abcdefghijklmnopqrstuvwxyz"
== "abcdefghijklmnopqrstuvwxyz"

red>> pick s 1
== #"a"

red>> pick s 26
== #"z"

red>> pick s 27
== none ; Index out of range

; -------------------------------------------------------------------------
; Using a block! of string!s
; -------------------------------------------------------------------------

red>> p: ["abc" "def" "ghi" "jkl" "mno" "pqr" "stu"]
== ["abc" "def" "ghi" "jkl" "mno" "pqr" "stu"]

red>> pick p 1
== "abc"

red>> pick p 4
== "jkl"

red>> pick p -1
== none ; Index out of range

top alphanumeric-index category-index



poke          type:  action!--    Cats: Series, String manipulation
The word poke changes an element of a series! to a value.

Arguments:
- name of the series!
- the index of the element to be replaced
- the new value for that element
Examples
; -------------------------------------------------------------------------
; Using a block! of numbers
; -------------------------------------------------------------------------

red>> x: [1 2 3 4 5 6 7 8 9]
== [1 2 3 4 5 6 7 8 9]

red>> poke x 3 66
== 66

red>> x
== [1 2 66 4 5 6 7 8 9]

red>> poke x 11 12
*** Script Error: value out of range: 11
*** Where: poke

; -------------------------------------------------------------------------
; using a string!
; -------------------------------------------------------------------------

red>> s: "abcdefghijklmnop"
== "abcdefghijklmnop"

red>> poke s 3 #"C"
== #"C"

red>> s
== "abCdefghijklmnop"

top alphanumeric-index category-index



positive?          type:  native!--    Cats: Comparison
The word positive? returns true if the numeric parameter 
is greater than 0, otherwise false.

NOTE that zero returns false.

Has one numeric parameter.
Examples
positive? -2
== false

positive? 0
== false

positive? 0.1
== true

top alphanumeric-index category-index



power          type:  action!--    Cats: Math
The word power returns the value of a number! raised to a given power (exponent).

It is the functional version of the infix word **.

It has 2 arguments: a base value and a power, both number!s.
Examples
red>> power 3.1 2
== 9.61

red>> power 100.9 0.5
== 10.04489920307815

red>> power 2 10
== 1024

top alphanumeric-index category-index



prin          type:  native!--    Cats: Console, Output
The word prin outputs a value to the Red console in a similar manner to 
the print word, but without emitting an end-of-line: "^(line)".

For more details, look at print.
Examples
red>> prin 3 + 3  prin 4 + 4 print "done"
68done

top alphanumeric-index category-index



print          type:  native!--    Cats: Console, Output
The word print outputs its evaluated argument to the Red console, 
followed by a new-line: "^(line)".

The single argument can be any type (also a block!). In this case
every block element is is evaluated. If you don't want evaluation,
investigate probe.

The twin word prin does the same but without outputting new-line.
Examples
red>> area: 3 * 2
== 6

red>> print area
6

red>> print area * 10
60

red>> print "Hello"
Hello

; Block is useful for printing several items
; Note: print will insert a space between the items in the block!
red>> print ["Area is" area "square units"]
Area is 6 square units

top alphanumeric-index category-index



probe          type:  function!--    Cats: Console
The word probe returns its argument, after printing it in its molded form.

Its argument can be any type. Blocks are not evaluated. This is useful for debugging.

Have a look at mold for specifics on the formatting.
Examples
; Behaviour of print
red>> print [1 + 2 44]
3 44

; Behaviour of probe and evaluation
red>> probe [1 + 2 44]
[1 + 2 44]

; Behaviour of mold
red>> probe [1 2 3]
[1 2 3]
== [1 2 3]

; Note the molded form
red>> probe #"A"
#"A"
== #"A"

; Same but now printed
red>> print probe #"A"
#"A"
A

top alphanumeric-index category-index



put          type:  action!--    Cats: Maps
USAGE:
PUT series key value

DESCRIPTION:
Replaces the value following a key, and returns the new value.
PUT is an action! value.

ARGUMENTS:
series [series! map! object!]
key [scalar! any-string! any-word! binary!]
value [any-type!]

REFINEMENTS:
/case => Perform a case-sensitive search.

RETURNS:
[series! map! object!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



pwd          type:  function!--    Cats: Directories
USAGE:
PWD

DESCRIPTION:
Displays the active directory path (Print Working Dir).
PWD is a function! value.
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



q          type:  function!--    
This word is a synonym for quit
top alphanumeric-index category-index


query          type:  action!--    Cats: Files
USAGE:
QUERY target

DESCRIPTION:
Returns information about a file.
QUERY is an action! value.

ARGUMENTS:
target [file!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



quit          type:  function!--    Cats: Exiting, System Related
The word quit quits the interpreter (and thus the program) immediately.

Refinement:
/return p - When this refinement is used value p is returned by quit.
Examples
quit
; returns immediately to the OS command prompt

quit/return 3
; returns to the OS command prompt and hands the OS the value 3

top alphanumeric-index category-index



quit-return          type:  routine!--    Cats: Exiting, System Related
The word quit-return stops evaluation and exits the program 
with a given return code.

The argument is the return code, an integer!.
Examples
data: 1234
either data > 0
[quit-return 1]
[quit-return 0]
; This program returns 1 to the OS. This is the program's return code.
; Ways of handling this depend on the particular OS.

top alphanumeric-index category-index



quote          type:  function!--    Cats: Word Manipulation
To do by red-by-example team ...


top alphanumeric-index category-index



random          type:  action!--    Cats: Math
The word random returns a random value of the same type as its single argument.
For certain types and refinements, it can shuffle or pick from a series!.

For an integer! argument of value n, the random value is between 1 and n inclusive.

Refinements
/seed - Restart or randomize
/secure - Returns a cryptographically secure random number!
/only - Pick a random value from a series!
Examples
red>> random 2
== 1

red>> random 2
== 2

red>> random 1.0
== 0.4107365828988778

red>> random "fish"
== "ifhs"

red>> random/only "abcde"
== #"a"

red>> random [1 2 3 4]
== [2 1 4 3]

red>> random/only ["stone" "paper" "scissors"]
== "scissors"

top alphanumeric-index category-index



react          type:  function!--    Cats: Reactivity
USAGE:
REACT reaction

DESCRIPTION:
Defines a new reactive relation between two or more objects.
REACT is a function! value.

ARGUMENTS:
reaction [block! function!] "Reactive relation."

REFINEMENTS:
/link => Link objects together using a reactive relation.
objects [block!] "Objects to link together."
/unlink => Removes an existing reactive relation.
src [word! object! block!] "'all word, or a reactor or a
list of reactors."
/later => Run the reaction on next change instead of now.
/with => Specifies an optional face object (internal use).
ctx [object! set-word! none!] {Optional context for VID
faces or target set-word.}

RETURNS:
The reactive relation or NONE if no relation was processed.
[block! function! none!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



react?          type:  function!--    Cats: Reactivity
USAGE:
REACT? reactor field

DESCRIPTION:
Returns a reactive relation if an object's field is a reactive source.
REACT? is a function! value.

ARGUMENTS:
reactor [object!] "Object to check."
field [word!] "Field to check."

REFINEMENTS:
/target => Check if it's a target instead of a source.

RETURNS:
Returns reaction, type or NONE.
[block! function! word! none!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



read          type:  action!--    Cats: Directories, Files, Input, URL/Internet
The word read reads and returns data from a file!.  

The argument must be a file! type.

Refinements:
/binary - reads, and preserves contents exactly
/lines - reads lines of text, placing them in a block! of string!s.
/info -
/part
/as
/seek
Examples
; The following example was executed on Windows, using a text file created with
; Notepad, and placed in the same folder as the program. The file contains 2 lines:

; LINE1
; LINE2

; Inside the file, the end of each line is marked by a CRLF pair.
; However, when Red reads the data as text, it presents the data to us with only
; the LF character at the end, just as on Linux.

; 1) read a file as strings

text: read %read-data.txt

print length? text ; 12 characters
12

prin text ; Displays all the lines. No extra newline
LINE1
LINE2

; 2) read a file as binary

bin: read/binary %read-data.txt

print length? bin ; 14 bytes
14

print bin ; In hex format
#{4C494E45310D0A4C494E45320D0A}

; 3) read individual lines (strings)

text: read/lines %read-data.txt

print length? pick text 1 ; Length is 5 - no LF
5

print pick text 2 ; Print second line
LINE

top alphanumeric-index category-index



read-clipboard          type:  routine!--    Cats: System Related
USAGE:
READ-CLIPBOARD

DESCRIPTION:
Return the contents of the system clipboard.
READ-CLIPBOARD is a routine! value.
; -------------------------------------------------------------------------
; write and read clipboard
; -------------------------------------------------------------------------

>> write-clipboard "Hello!!!"
== true
>> read-clipboard
== "Hello!!!"

top alphanumeric-index category-index



read-thru          type:  function!--    Cats: Files, Input, URL/Internet
USAGE:
READ-THRU url

DESCRIPTION:
Reads a remote file through local disk cache.
READ-THRU is a function! value.

ARGUMENTS:
url [url!] "Remote file address."

REFINEMENTS:
/update => Force a cache update.
/binary => Use binary mode.
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



rebol          type:  logic!--    Cats: System Related
REBOL is a logic! value: false
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



recycle          type:  native!--    Cats: System Related
USAGE:
RECYCLE

DESCRIPTION:
RECYCLE is a native! value.

REFINEMENTS:
/on =>
/off =>
Triggers a manual garbage collection pass, rather than waiting for internal
heuristics and timing events to do so. Recycle has 2 refinements: /off and /on.
They allow you to disable the garbage collector, and re-enable it. This
gives you control in scenarios where you want to manage things more directly
yourself.

top alphanumeric-index category-index



red-complete-input          type:  function!--    Cats: Input
USAGE:
RED-COMPLETE-INPUT str console?

DESCRIPTION:
RED-COMPLETE-INPUT is a function! value.

ARGUMENTS:
str [string!]
console? [logic!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



reduce          type:  native!--    Cats: Evaluation
The word reduce returns a copy of a block!, evaluating all expressions
in the block!.

Its single argument can be of any type.

See also: rejoin - which means 'reduce and join'.

Refinements
/into - puts results into a provided block!, instead of creating a new one.

Examples
red>> reduce[1 + 2 5 * 6]
[3 30]

red>> b: reduce[1 + 5]
[6]

red>> b
[6]

; -------------------------------------------------------------------------
; Use the /into refinement
; -------------------------------------------------------------------------


red>> a-block: []
[]

red>> reduce/into [4 5 + 6] a-block
[]

red>> a-block
[4 11]

; -------------------------------------------------------------------------
; Evaluating can also mean assignment
; -------------------------------------------------------------------------


red>> var: 3
3

red>> reduce [ 3 * 3 var: 22]
[9 22]

red>> var
22

; -------------------------------------------------------------------------
; Single values, variables or expressions (not in a block)
; -------------------------------------------------------------------------


red>> reduce 123
123

red>> reduce 1 + 2
3

top alphanumeric-index category-index



refinement!          type:  datatype!--    Cats: Datatypes
A refinement! datatype! indicates a variation in the use of, or 
extension in the meaning of, a function!, object!, file!, url!, or
path!. The exact usage of a refinement varies. For example,
function refinements can be written so they require additional
arguments. We might also use several refinements at once. Refinements
start with a /, followed by a valid Red word. Below, we use the
refinement? function to examine some possibilities.

Examples
; -------------------------------------------------------------------------
; try refinement?
; -------------------------------------------------------------------------

red>> refinement? /part
== true
red>> refinement? /45
== true
red>> refinement? /:b ; this is a set-word! type
== false

; -------------------------------------------------------------------------
; refinement with function. The 3 is the argument of /part
; -------------------------------------------------------------------------

red>> s: [8 7 6 5 4 3 2]
red>> sort/part s 3
== [6 7 8 5 4 3 2] ; Only the first 3 items were sorted

; -------------------------------------------------------------------------
; refinement with an object
; -------------------------------------------------------------------------

red>> print system/version
== 0.6.1

; -------------------------------------------------------------------------
; refinement as a path to a block element
; -------------------------------------------------------------------------

red>> b: [11 22 33 44]
red>> b/2
== 22

top alphanumeric-index category-index



refinement?          type:  function!--    Cats: Type Checking
The refinement? word returns true if the single argument is a 
refinement, otherwise false.

Note that the argument is not checked against all existing refinements,
merely that it fits the syntax for a refinement.

The single argument can be of any type.
Examples
red>> refinement? /all
true

red>> refinement? /nonsense
true

red>> refinement? /123
true

; -------------------------------------------------------------------------
; Invalid: string is not a refinement
; -------------------------------------------------------------------------


red>> refinement? "/abc"
false

red>> r: "/abc"
"/abc"

red>> refinement? r
false

; -------------------------------------------------------------------------
; Valid: a refinement can be stored in a variable
; -------------------------------------------------------------------------


red>> r: /abc
== /abc

red>> refinement? r
== true

top alphanumeric-index category-index



reflect          type:  action!--    Cats: Reflection
Returns internal details about a value via reflection. 

Arguments

value - of a type that supports reflection
field - a word! such as spec, body, words, etc. Each datatype!
defines its own reflectors.

Examples
; -------------------------------------------------------------------------
; reflect with a map: 'body, 'values
; -------------------------------------------------------------------------

red>> m: make map![a 1 b 2]
red>> reflect m 'body
== [a: 1 b: 2]

red>> reflect m 'values
== [1 2]

; -------------------------------------------------------------------------
; reflect with object: 'body 'values 'words
; -------------------------------------------------------------------------

red>> place: make object! [
x-pos: 100
y-pos: 200
]

red>> reflect place 'body
== [x-pos: 100 y-pos: 200]

red>> reflect place 'values
== [100 200]

red>> reflect place 'words
== [x-pos y-pos]

top alphanumeric-index category-index



rejoin          type:  function!--    Cats: Series, String manipulation
Accepts a block of items, reduces them, and joins them together.  No 
spaces are inserted between items. The rejoined item is returned, and the
original block is unaltered.

REBOL users please note - Red does not have 'join'.

Arguments
A block.


Examples

; -------------------------------------------------------------------------
; Some simple rejoins - note the string! result
; -------------------------------------------------------------------------

>> b: ["sum is " 3 + 2]
== ["sum is " 3 + 2]
>> rejoin b
== "sum is 5"
>> type? rejoin b
== string!

>> b2: [3 + 4 " is result"]
== [3 + 4 " is result"]
>> rejoin b2
== "7 is result"

; -------------------------------------------------------------------------
; Join some blocks - note the appended series
; -------------------------------------------------------------------------

>> rejoin [b b2]
== ["sum is " 3 + 2 [3 + 4 " is result"]]

; -------------------------------------------------------------------------
; The tag! type acts differently. The result is a tag! type
; -------------------------------------------------------------------------

>> rejoin [<a href=test.html> "test" </a>]
>> <a href=test.htmltest</a>>

;-- we could convert to strings to get a more useful result:
>> rejoin ["<a href=test.html>" "test" </a>]
== "<a href=test.html>test</a>"

top alphanumeric-index category-index



remainder          type:  action!--    Cats: Math
The word remainder returns the rest of dividing the first by the second value.

Has 2 arguments of type:
number! char! pair! tuple! vector!

It is the functional version of the infix word //.

If the first argument is positive, then the remainder is positive.

If the first argument is negative, then the remainder is negative,
as in remainder -5 4, which results in -1.

If the first argument is zero, then the remainder is also zero.

If the second argument is zero, a run-time error occurs.
Examples
red>> remainder 5 4
== 1

red>> remainder 5 5
== 0

red>> remainder 5 6
== 5
; 5 divided by 6 gives zero
; with remainder of 5

red>> remainder -5 4
== -1

red>> remainder 10 3.3
== 0.1000000000000005

red>> remainder 5x10 4
== 1x2

red>> remainder make vector![5 5 10] 4
== make vector! [1 1 2]

top alphanumeric-index category-index



remove          type:  action!--    Cats: Series, String manipulation
The word remove removes the first value(s) from a series!
and returns the modified series! from the removal point onwards.

The single argument can be of type:
series!
bitset!
none!

Refinements
/part - removes a number of values, or values up to the
given index.
This refinement requires one of:
number!
char!
series!

Note that for a bitset! argument, the /part refinement is required.

Note that remove is destructive. It changes the series! involved!!
Examples
; -------------------------------------------------------------------------
; Setup 2 variables to be used in the examples
; -------------------------------------------------------------------------

red>> data: [22 11 44 66 10]
== [22 11 44 66 10]

red>> s: "abcdefg"
== "abcdefg"

; -------------------------------------------------------------------------
; Remove first item of a series!
; -------------------------------------------------------------------------

red>> remove data
== [11 44 66 10]

red>> data
== [11 44 66 10]

; -------------------------------------------------------------------------
; Remove first item of a string!
; -------------------------------------------------------------------------

red>> remove s
== "bcdefg"

red>> s
== "bcdefg"

; -------------------------------------------------------------------------
; Remove the first 2 items using /part
; -------------------------------------------------------------------------

red>> remove/part data 2
== [66 10]

red>> data
== [66 10]

red>> remove/part s 2
== "defg"

red>> s
== "defg"

; -------------------------------------------------------------------------
; Bitset (E.g. hex code for "A" is 65, so the 65th bit is set)
; -------------------------------------------------------------------------

red>> b: make bitset![#"A" #"N"]
make bitset! #{00000000000000004002}

red>> remove/part b #"N"
make bitset! #{00000000000000004000}

; -------------------------------------------------------------------------
; Use /part with a series! index
; -------------------------------------------------------------------------

red>> nums: [1 2 3 4 5 6 7 8]
== [1 2 3 4 5 6 7 8]

red>> ref: skip nums 4
== [5 6 7 8]

red>> remove/part nums ref
== [5 6 7 8]

red>> nums
== [5 6 7 8]

red>> ref
== []

top alphanumeric-index category-index



remove-each          type:  native!--    Cats: Series
Removes one or more values from a series!.  
A block is evaluated for each element, and the element is removed
if the block is true. The original series is modified.

Arguments

word - a word! or block! of words to set.
These are used in the evaluation. They are not local.

data - a series!, which includes string!

body - a block! to be evaluated.

Examples
;remove-each, with only one 'word' argument
;make a series s to work with
red>> s: [3 6 "text" 12 15 "end"]

;remove each string element
red>> remove-each this-item s [string? this-item]
;note the modified series
red>> s
== [3 6 12 15]

;remove each item > 6
red>> remove-each this-item s [this-item > 6]
;note modified series
red>> s
== [3 6]

;a string of characters - remove all spaces
red>> text: "a few words with spaces"
red>> remove-each ch text [ch = #" "]
;check the result
red>> text
== "afewwordswithspaces"

top alphanumeric-index category-index



repeat          type:  native!--    Cats: Iteration
The word repeat evaluates a given block! a specified number of times 
and exposes the count value to the block! being executed.

Has 3 parameters:
1. name of a count variable, which contains the current value of the counter
2. number of times the block! should be evaluated
3. the block! to be evaluated

Warning:
1. the count variable can only be referred within the block!;
so, if before the repeat a variable exists with the same name,
that variable will be untouched after repeat
2. when repeat introduces a unique name for count, that name
cannot be referenced anymore after repeat
Examples
counter: 33
== 33
repeat counter 4 [print ["Evaluation #" counter]]
Evaluation # 1
Evaluation # 2
Evaluation # 3
Evaluation # 4
>> counter
== 33

repeat x 3 [print ["Evaluation #" x]]
Evaluation # 1
Evaluation # 2
Evaluation # 3
>> x
** Script Error: x has no value
** Near: x

repeat y 5 [y: y - 1 print ["y =" y]]
y = 0
y = 1
y = 2
y = 3
y = 4

top alphanumeric-index category-index



repend          type:  function!--    Cats: Series
Appends a reduced value to a series and returns the series head.   
The original series is modified.

Arguments
- a series!
- a value to be appended, of any type.

Refinements
/only - Appends a block value as a block.

Examples
; -------------------------------------------------------------------------
; repend a block - note the evaluation
; -------------------------------------------------------------------------

;make a series to work with
red>> s: [10 "eleven" 12]

red>> repend s [7 + 7 "fifteen"]
== [10 "eleven" 12 14 "fifteen"]
;s has changed
red>> s
== [10 "eleven" 12 14 "fifteen"]

; -------------------------------------------------------------------------
; /only refinement - note nested block
; -------------------------------------------------------------------------

red>> repend/only s [7 + 7 "fifteen"]
== [10 "eleven" 12 14 "fifteen" [14 "fifteen"]]

top alphanumeric-index category-index



replace          type:  function!--    Cats: Series, String manipulation
The word replace replaces the search-value with the replace value 
in a series!.

It can be used with strings, because a string! is a series!.

It has 3 arguments:
series - the series! to be modified.
search-value - the value to be replaced (any type)
replace-value - the value to replace with (any type)

The search is case-insensitive and only the first occurrence is replaced,
unless the refinement /all is used.

The replaced and replacing item can have a different length.

Refinements
/all - replace all occurrences

Note that this is a destructive operation. It alters the series!
involved!
Examples
; -------------------------------------------------------------------------
; Replace a by W
; -------------------------------------------------------------------------


red>> s: "abcde"
"abcde"

red>> replace s "a" "W"
"Wbcde"

red>> s
"Wbcde"

; -------------------------------------------------------------------------
; Note the case insensitivity here
; -------------------------------------------------------------------------


red>> a-string: "The cat and the dog"
"The cat and the dog"

red>> replace a-string "the" "a"
"a cat and the dog"

; -------------------------------------------------------------------------
; Using the /all refinement
; -------------------------------------------------------------------------


red>> river: "Mississippi"
"Mississippi"

red>> replace/all river "is" "IS"
"MISsISsippi"

; -------------------------------------------------------------------------
; A series of numbers
; -------------------------------------------------------------------------


red>> nums: [21 22 23 -1 44 45 46]
[21 22 23 -1 44 45 46]

red>> replace nums -1 [33 34 35]
[21 22 23 33 34 35 44 45 46]

red>> replace nums [21 22 23] -1
[-1 33 34 35 44 45 46]

top alphanumeric-index category-index



return          type:  native!--    Cats: Exiting
The word return returns a value from a function. 
It needs one argument, of any type.

In functions which don't have a return value, you can use the word exit.

Under special conditions it is useful to return the value none.

The value of a block! is the value of last evaluation that takes place in it,
so this can be used to return a value, without using the return word.

If we want to return a value partway through a block!, or want to make it
more explicit for a reader of the code, we also can use return.
Examples
bigger: func [a b] [
either a > b [
return a
][
return b
]
]
print bigger 8 6
8

top alphanumeric-index category-index



reverse          type:  action!--    Cats: Series, String manipulation
The word reverse reverses the order of elements in its argument.  
The argument will be changed. Returns at the same position in the argument.

The argument can be a:
series!
pair!
tuple!

Refinements
/part - limits to a given length or position (number! series!)

Note:
- for series! reverse is destructive
- but not for tuple! and pair!
Examples
; -------------------------------------------------------------------------
; Reverse a block! series!
; -------------------------------------------------------------------------

red>> b: [1 2 3 4]
== [1 2 3 4]

red>> reverse b
== [4 3 2 1]

red>> b
== [4 3 2 1]

red>> s: "ABCD"
== "ABCD"

red>> reverse s
== "DCBA"

red>> s
== "DCBA"

; -------------------------------------------------------------------------
; Reverse a section of a string! series!
; -------------------------------------------------------------------------

red>> words: "The black cat"
== "The black cat"

red>> reverse find words "cat"
== "tac"

red>> words
== "The black tac"

; -------------------------------------------------------------------------
; Use refinement /part - reverse first 3
; -------------------------------------------------------------------------

red>> s: "abcdefg"
== "abcdefg"

red>> reverse/part s 3
== "cbadefg"

red>> s
== "cbadefg"

; -------------------------------------------------------------------------
; Reverse all values before value 50
; -------------------------------------------------------------------------

red>> b: [10 20 30 40 50 60 70]
== [10 20 30 40 50 60 70]

red>> reverse/part b find b 50
== [40 30 20 10 50 60 70]

red>> b
== [40 30 20 10 50 60 70]

; -------------------------------------------------------------------------
; Reverse a tuple - note unchanged value of t afterwards!
; -------------------------------------------------------------------------

red>> t: 11.22.33.44.55
== 11.22.33.44.55

red>> reverse t
== 55.44.33.22.11

red>> t
== 11.22.33.44.55

; -------------------------------------------------------------------------
; Reverse a pair - note unchanged value of p afterwards!
; -------------------------------------------------------------------------

red>> p: 100x200
== 100x200

red>> reverse p
== 200x100

red>> p
== 100x200

top alphanumeric-index category-index



round          type:  action!--    Cats: Math
Returns the nearest integer value.  Halves round up (away from zero) by
default. Note that refinements allow decimal places (etc) to be specified.

Arguments
The single argument can be a number! or a time!

Refinements
/to - Return the nearest multiple of the scale parameter.
We supply a non-zero number!
/even - Halves round toward even results.
/down - Round toward zero, ignoring discarded digits - i.e. truncate.
/half-down - Halves round toward zero, not away from zero.
/floor - Round in negative direction.
/ceiling - Round in positive direction.
/half-ceiling - Halves round in positive direction.


Examples
; -------------------------------------------------------------------------
; round - no refinements
; -------------------------------------------------------------------------

;basic use
red>> round 2.3
== 2.0

;note -ve - round toward zero
red>> round -3.3
== -3.0

;halves round away from zero
red>> round 2.5
== 3.0
red>> round -3.5
== -4.0

;time argument - note rounded seconds
red>> round 13:14:15.6
== 13:14:16

; -------------------------------------------------------------------------
; /to refinement
; -------------------------------------------------------------------------

red>> round/to 12.36 0.1
== 12.4
red>> round/to 2888 100
== 2900

; -------------------------------------------------------------------------
; /even refinement
; -------------------------------------------------------------------------

;towards even: 4 not 5
red>> round/even 4.5
== 4.0
;towards even: 4 not 3
red>> round 3.5
== 4.0
red>> round 4.5
== 5.0

; -------------------------------------------------------------------------
; /down refinement
; -------------------------------------------------------------------------

red>> round/down 3.9
== 3.0
red>> round/down -3.9
== -3.0

; -------------------------------------------------------------------------
; /half-down refinement
; -------------------------------------------------------------------------

red>> round/half-down 2.5
== 2.0
red>> round/half-down -3.5
== -3.0

; -------------------------------------------------------------------------
; /floor refinement
; -------------------------------------------------------------------------

red>> round/floor 3.9
== 3.0
red>> round/floor -3.9
== -4.0

; -------------------------------------------------------------------------
; /ceiling refinement
; -------------------------------------------------------------------------

red>> round/ceiling 3.2
== 4.0
red>> round/ceiling -3.9
== -3.0

; -------------------------------------------------------------------------
; /half-ceiling refinement
; -------------------------------------------------------------------------

red>> round/half-ceiling 3.5
== 4.0
red>> round/half-ceiling -3.5
== -3.0

top alphanumeric-index category-index



routine          type:  function!--    Cats: Functions, System Related
USAGE:
ROUTINE spec body

DESCRIPTION:
Defines a function with a given Red spec and Red/System body.
ROUTINE is a function! value.

ARGUMENTS:
spec [block!]
body [block!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



routine!          type:  datatype!--    Cats: Datatypes, Functions
The datatype! routine! is used to link up to external code.  

Once a library has been loaded, it is possible to create a routine!
type to access the external function from Red.

You can use make to create a new, named routine!.
Examples
; -------------------------------------------------------------------------
; Use make to create a routine!
; -------------------------------------------------------------------------


; red-routine-name: make routine! specs library-name func-id

; -------------------------------------------------------------------------
; Docs to be extended by red-by-example team ...
; -------------------------------------------------------------------------




top alphanumeric-index category-index



routine?          type:  function!--    Cats: Functions, Type Checking
The word routine? returns true if its argument is a routine!,
otherwise false.

A routine! is a function in an external library.

Its single argument can be of any type.
Examples
; -------------------------------------------------------------------------
; The word cos is external
; -------------------------------------------------------------------------

red>> routine? :cos ; Note the colon!
true

; -------------------------------------------------------------------------
; The word sort is not in an external library
; -------------------------------------------------------------------------

red>> routine? :sort
false


top alphanumeric-index category-index



same?          type:  native!--    Cats: Comparison, Type Checking
The word same? returns true if the arguments refer to 
identical objects, otherwise false.

For example, true would be returned if two strings are the
same string (that is: they occupy the same memory location).

The two arguments can be of any type.
Examples
; -------------------------------------------------------------------------
; Same string, but in differnet memory locations
; -------------------------------------------------------------------------

red>> a: "fish"
"fish"

red>> b: "fish"
"fish"

red>> same? a b
false

; -------------------------------------------------------------------------
; Same string and same memory location
; -------------------------------------------------------------------------

red>> a: "meat"
"meat"

red>> b: a
"meat"

red>> same? a b
true

top alphanumeric-index category-index



save          type:  function!--    Cats: Files
The word save is used to save Red code to a file!, url!, 
binary! or string!.

The load word is intended for reading back items created with save.
Note that write is intended for storing data, not code.

Red uses brackets [ ] { } and quotes " " etc. to enclose data items.
The items might or might not be code. In a sense they become code when
we instruct Red to interpret them. Because of this, save can be
used to save data as well as code. In fact, there is no difference.
Red has the same adagium as Lisp: ; Code = Data.

The word save has 2 arguments:
where to save - one of
file! url! binary! string! none!
value - the value(s) to save

Refinements:
/header - provide a Red header block (or output non-code datatypes).
This requires header-data (a block!) or an object!
/all - save in serialized format. (Not available yet)
/length - save the length of the script content in the header
/as - specify the format of data; use NONE to save as plain text;
format [word! none!] => E.g. json, html, jpeg, png, redbin etc.
Examples
; -------------------------------------------------------------------------
; Save 2 lines of code in a file mydata.r
; -------------------------------------------------------------------------

red>> code: [
[ print "Hello"
[ print "Goodbye"
[ ]
== [
print "Hello"
print "Goodbye"
]

red>> save %mydata.r code

; -------------------------------------------------------------------------
; Load the just saved data back
; -------------------------------------------------------------------------

red>> load %mydata.r
[print "Hello"
print "Goodbye"
]

; -------------------------------------------------------------------------
; We can use do to interpret the code in the file
; -------------------------------------------------------------------------

red>> do %mydata.r
Hello
Goodbye

red>> do code
Hello
Goodbye

; -------------------------------------------------------------------------
; Save some structured data
; -------------------------------------------------------------------------

red>> data: [ [1 10] [2 20] 30]
== [[1 10] [2 20] 30]

red>> save %mydata.r data

; -------------------------------------------------------------------------
; Load that data back
; -------------------------------------------------------------------------

red>> load %mydata.r
== [[1 10] [2 20] 30]


top alphanumeric-index category-index



scalar!          type:  typeset!--    Cats: Datatypes
scalar! is a typeset! value:
make typeset! [char! integer! float! pair! percent! tuple! time! date!]


top alphanumeric-index category-index



scalar?          type:  function!--    Cats: Type Checking
Returns true if the value is any type of scalar!. 

Arguments

One, which can be any-type!

Examples

; -------------------------------------------------------------------------
; Explore several types
; -------------------------------------------------------------------------

>> scalar? "abc" ;-- a string is a series type, not scalar
== false

>> scalar? 24
== true
>> scalar? 2.3
== true
>> scalar? 20x30
== true

top alphanumeric-index category-index



second          type:  function!--    Cats: Series, String manipulation
The word second returns the second value of a series!. 

The argument can be one of:
series! tuple! pair!

If there is no second item in the series!, none is returned.
Examples
; -------------------------------------------------------------------------
; Second of a block!
; -------------------------------------------------------------------------

red>> second [3 4 5]
4

; -------------------------------------------------------------------------
; Second of a string! (a char!)
; -------------------------------------------------------------------------

red>> second "ABC"
#"B"

; -------------------------------------------------------------------------
; A series! having no second element
; -------------------------------------------------------------------------

red>> second [44]
none

; -------------------------------------------------------------------------
; Second of a tuple!
; -------------------------------------------------------------------------

red>> second 66.77.88
77

; -------------------------------------------------------------------------
; Second of a pair!
; -------------------------------------------------------------------------

red>> second 22x55
55

top alphanumeric-index category-index



select          type:  action!--    Cats: Series, String manipulation
The word select finds a value in a series! and if succesful returns 
the element right after the element found. Returns none if the search fails.

Select is similar to the find function.

The 2 arguments are:
a series - of type series! any-object! map! none!
a value - of any type

Refinements
/part - Limit the length (a number!) of the search or a series! reference.
/only - Treat a series search value as a single value.
/case - Perform a case-sensitive search.
/any - Use * and ? wildcards in string searches.
/with - Use custom wildcards * or ?.
/skip - Treat the series as fixed size records. Requires an integer! size.
/last - Find the last occurrence of value (from the tail).
/reverse - Find the last occurrence of value (from the current index).

Examples
; -------------------------------------------------------------------------
; Select a month, return item following it
; -------------------------------------------------------------------------

red>> months: ["Mar" 31 "April" 30 "May" 31]
== ["Mar" 31 "April" 30 "May" 31]

red>> select Months "April"
== 30

red>> select Months 30
== "May" ; Beware that select can match any element!

; -------------------------------------------------------------------------
; Select a character in a string! (after D)
; -------------------------------------------------------------------------

red>> str: "ABCDEFGH"
== "ABCDEFGH"

red>> select str "D"
== #"E" ; Because E follows the found element D

; -------------------------------------------------------------------------
; /pairs - do a normal select, then use /pairs
; -------------------------------------------------------------------------

red>> pairs: [44 4 3 33 4 55]
== [44 4 3 33 4 55]

red>> select pairs 4
== 3 ; Because 3 follows the found element 4

; -------------------------------------------------------------------------
; Select only matches the first element in a skip group
; -------------------------------------------------------------------------

red>> select/skip pairs 4 2
== 55

; -------------------------------------------------------------------------
; Search form the tail
; -------------------------------------------------------------------------

red>> animal: "The black cat"
== "The black cat"

red>> select/last animal "a"
== #"t"

; -------------------------------------------------------------------------
; Using the /only refinement
; -------------------------------------------------------------------------

red>> blk: [11 12 13 [22 33 44] 15]
== [11 12 13 [22 33 44] 15]

red>> select blk 13
== [22 33 44]

red>> select blk [22 33 44]
== none ; Not found, because we searched for a series!

red>> select/only blk [22 33 44]
15

red>> select/only blk [22 33 44]
== 15 ; Success! With /only we can search for a series!

; -------------------------------------------------------------------------
; Search backwards from a position with the /reverse refinement
; -------------------------------------------------------------------------

red>> words: "a-few-words"
== "a-few-words"

red>> current: find/last words "-"
"-words"

red>> current: find/last words "-"
== "-words"

red>> index? current
== 6

red>> select/reverse current "-"
== #"f"

top alphanumeric-index category-index



series!          type:  typeset!--    Cats: Datatypes
The datatype! series! is a typeset! containing several datatype!s.
Examples
; -------------------------------------------------------------------------
; Show all series! types
; -------------------------------------------------------------------------

red>> ? series!
series! is a typeset! of value:
make typeset! [
block!
paren!
string!
file!
url!
path!
lit-path!
set-path!
get-path!
vector!
hash!
binary!
image!
]

top alphanumeric-index category-index



series?          type:  function!--    Cats: Type Checking
word series? returns true if its argument is a
series!, otherwise false.

The argument can be of any type.

The series! type includes:
block!
paren!
string!
file!
url!
path!
lit-path!
set-path!
get-path!
vector!
hash!
binary!
image!
Examples
; -------------------------------------------------------------------------
; A block!
; -------------------------------------------------------------------------

red>> series? [1 "text"]
true

; -------------------------------------------------------------------------
; A tuple!
; -------------------------------------------------------------------------

red>> series? 12.33.12
false

; -------------------------------------------------------------------------
; A string!
; -------------------------------------------------------------------------

red>> series? "ABC"
true

; -------------------------------------------------------------------------
; A float!
; -------------------------------------------------------------------------

red>> series? 12.34
false

top alphanumeric-index category-index



set          type:  native!--    Cats: Word Manipulation
USAGE:
SET word value

DESCRIPTION:
Sets the value(s) one or more words refer to.
SET is a native! value.

ARGUMENTS:
word [any-word! block! object! path!] "Word, object, map path
or block of words to set."
value [any-type!] "Value or block of values to assign to words."

REFINEMENTS:
/any => Allow UNSET as a value rather than causing an error.
/case => Use case-sensitive comparison (path only).
/only => Block or object value argument is set as a single value.
/some => None values in a block or object value argument, are
not set.

RETURNS:
[any-type!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



set-current-dir          type:  routine!--    Cats: Files
USAGE:
SET-CURRENT-DIR path

DESCRIPTION:
Sets the platform’s current process directory.
SET-CURRENT-DIR is a routine! value.

ARGUMENTS:
path [string!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



set-env          type:  native!--    Cats: System Related
USAGE:
SET-ENV var value

DESCRIPTION:
Sets the value of an operating system environment variable (for current process).
SET-ENV is a native! value.

ARGUMENTS:
var [any-string! any-word!] "Variable to set."
value [string! none!] "Value to set, or NONE to unset it."
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



set-path!          type:  datatype!--    Cats: Datatypes
A set-path! is a kind of path! used to change (set) a value.  Refer 
to path! and set-word! for more details.

Examples
; -------------------------------------------------------------------------
; Use a set-path!, and check the type.
; -------------------------------------------------------------------------

red>> b:[11 22 33 44]

;note the trailing colon
red>> b/2: -999
== -999
;note the changed value
red>> b
== [11 -999 33 44]
;now with a variable
red>> place: 3
== 3
;the first : gets the value of place, second makes a set-path!
red>> b/:place: -1000
== -1000
red>> b
== [11 -999 -1000 44]

;Find the type - first [block] is used to prevent evaluation
red>> type? first [b/:place:]
== set-path!

top alphanumeric-index category-index



set-path?          type:  function!--    Cats: Type Checking
This word returns true if its argument is a set-path! type, otherwise false.

Its single argument can be any type.

Examples
; -------------------------------------------------------------------------
; use set-path? on various types
; -------------------------------------------------------------------------

;create a block and position to work with
red>> b: [11 22 33]
red>> n: 2

;get-path? with an evaluated path
red>> set-path? b/2:
*** Script Error: b/2: needs a value
*** Where: set-path?

;now use first [ block ] to prevent evaluation
red>> set-path? first [b/2:]
== true
red>> set-path? first [b/:n:]
== true
;this is a path!
red>> set-path? first [b/n]
== false

top alphanumeric-index category-index



set-quiet          type:  routine!--    Cats: GUI: VID, View
USAGE:
SET-QUIET word value

DESCRIPTION:
Set an object's field to a value without triggering object's events.
SET-QUIET is a routine! value.

ARGUMENTS:
word [any-type!]
value [any-type!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



set-word!          type:  datatype!--    Cats: Datatypes
Red has a notation which modifies how a word is evaluated.  The colon and 
single quote mark ('tick') are used. For example, for a word w, we have:

w: - sets the word to a value. Its type is set-word!
:w - gets the word's value, but does not evaluate it. Its type is
get-word!
'w - treat the word as a symbol, with no evaluation. Its type is
lit-word! (i.e. literal word).
w - normal evaluation. If the word is a function, evaluate it.

Note that : and ' are not functions. Attaching them to a word changes the
type of the word, and how it is used.

We can use the set-word? , get-word?, lit-word? functions to
test whether a word is one of these types.

The set-word! type sets a word to a value. It is tempting for beginners
to assume that a colon is like an assignment operator in other languages, but
this is not the case. It specifies the use of a set-word! type, which expects
a value.

Examples
; -------------------------------------------------------------------------
; Use a set-word! type
; -------------------------------------------------------------------------

;provide a value
red>> a-word: 123

;a-word set to 999, then w set to a-word's value, 999
red>> w: a-word: 999

;the type of an unevaluated set-word
red>> type? first [ a: ]
== set-word!

top alphanumeric-index category-index



set-word?          type:  function!--    Cats: Type Checking
Returns true if its argument is a set-word! type, otherwise false.

Its single argument can be of any type.

Examples
; -------------------------------------------------------------------------
; A few types of argument
; -------------------------------------------------------------------------

red>> a-word: 123

;just a normal word
red>> set-word? a-word
== false

;correct set-word! syntax, but its value is not a reference
red>> set-word? a-word:
*** Script Error: a-word: needs a value
*** Where: a-word

;prevent evaluation with first [block]
red>> set-word? first [a-word:]
== true

;a get-word!
red>> set-word? first [:a-word]
== false

top alphanumeric-index category-index



shift          type:  native!--    Cats: Bit manipulation
The word shift performs an arithmetical bit shift operation, 
preserving the sign.

By default it shifts to the right, but left shifting is also possible.

A single right shift divides by 2.
A single left shift multiplies by 2.

Also logical shifting is possible.

It has 2 arguments:
- an integer! to be shifted
- an integer! stating how many places to shift

Note: the infix << >> >>> operators provide similar facilities.

Refinements
/left - shift bits to the left instead of to the right
/logical - use logical shift (unsigned, fill with zeroes)
Examples
; -------------------------------------------------------------------------
; Right-shift a positive number
; -------------------------------------------------------------------------

red>> shift 64 2
== 16

red>> to-hex 64
== #00000040

red>> to-hex 16
== #00000010

; -------------------------------------------------------------------------
; Right-shift a negative number, preserving sign
; -------------------------------------------------------------------------

red>> shift -1 4
== -1

red>> to-hex -1
== #FFFFFFFF ; Left most bit stays 1 (= negative)

; -------------------------------------------------------------------------
; Left-shift a positive number
; -------------------------------------------------------------------------

red>> shift/left 64 2
== 256

red>> to-hex 64
== #00000040

red>> to-hex 256
== #00000100

; -------------------------------------------------------------------------
; Left-shift a negative number, preserving sign
; -------------------------------------------------------------------------

red>> shift/left -1 4
== -16

red>> to-hex -1
== #FFFFFFFF

red>> to-hex -16
== #FFFFFFF0

; -------------------------------------------------------------------------
; Logical right-shift, no sign preservation
; -------------------------------------------------------------------------

red>> shift/logical -1 4
== 268435455

red>> to-hex -1
== #FFFFFFFF

red>> to-hex 268435455
== #0FFFFFFF

top alphanumeric-index category-index



shift-left          type:  routine!--    Cats: Bit manipulation
The word shift-left performs a logical shift-left operation.  
The sign-bit is not preserved.

A single shift-left multiplies by 2.

It has 2 arguments:
- an integer! value to be shifted
- an integer! stating how many places to shift.

Note that the infix words << >> >>> provide similar
facilities.
Examples
; -------------------------------------------------------------------------
; Normal shift-left
; -------------------------------------------------------------------------

red>> to-hex 64
== #00000040

red>> shift-left 64 2
256

red>> to-hex shift-left 64 2
== #00000100

; -------------------------------------------------------------------------
; Sign bit changed by shift ...
; -------------------------------------------------------------------------

red>> to-hex 1
== #00000001

red>> to-hex shift-left 1 31
== #80000000 ; Left most bit (sign bit) changed

red>> shift-left 1 31
== -2147483648 ; See, it it negative!

red>> to-hex shift-left 1 32
== #00000001 ; Wrapped around by 32 bits now

top alphanumeric-index category-index



shift-logical          type:  routine!--    Cats: Bit manipulation
The word shift-logical performs a logical right shift. 
The sign is not preserved.

It has 2 arguments:
- an integer! value to be shifted
- an integer! stating how many bitss to shift

Note that the infix << >> >>> operators provide similar facilities.
Examples
; -------------------------------------------------------------------------
; Shift (right) by 2 bits
; -------------------------------------------------------------------------

red>> to-hex 64
== #00000040 ; Last byte = binary 0100 0000

red>> shift-logical 64 2
== 16

red>> to-hex shift-logical 64 2
== #00000010 ; Last byte = binary 0001 0000

; -------------------------------------------------------------------------
; Shift (right) by 1 bit - note zero entering at the left
; -------------------------------------------------------------------------

red>> to-hex -1
== #FFFFFFFF ; First byte = binary 1111 1111

red>> shift-logical -1 1
== 2147483647

red>> to-hex shift-logical -1 1
== #7FFFFFFF ; First byte = binary 0111 1111

top alphanumeric-index category-index



shift-right          type:  routine!--    Cats: Bit manipulation
The word shift-right performs a right-shift operation.

A single shift-right divides by 2.

It has 2 arguments:
- an integer! value to be shifted
- an integer! stating how many places to shift

Note that the infix << >> >>> operators provide
similar facilities.
Examples
; -------------------------------------------------------------------------
; Normal shift
; -------------------------------------------------------------------------

red>> shift-right 16 2
== 4

; -------------------------------------------------------------------------
; Negative sign (left most bit) will be preserved
; -------------------------------------------------------------------------

to-hex -2147483648
== #80000000 ; #80 is binary 1000 0000

red>> shift-right -2147483648 1
== -1073741824

red>> to-hex -1073741824
== #C0000000 ; #C0 is binary 1100 0000



top alphanumeric-index category-index



sign?          type:  native!--    Cats: Math
docstart
USAGE:
SIGN? number

DESCRIPTION:
Returns sign of N as 1, 0, or -1 (to use as a multiplier).
SIGN? is a native! value.

ARGUMENTS:
number [number! time!]
.docend
Examples
>> sign? 33.5
== 1

top alphanumeric-index category-index



sin          type:  function!--    
This word is a synonym for sine
top alphanumeric-index category-index


sine          type:  native!--    Cats: Math
The word sine returns the trigonometric sine.

Has 1 parameter, a number! (representing an angle).

Refinements:
/radians : expects the input angle in radians;
without refinement expects the input angle in degrees.
Examples
sine 90
== 1.0

sine/radians pi
== 0.0

sine/radians pi + 0.003
== -0.002999995500002016

top alphanumeric-index category-index



size?          type:  native!--    Cats: Files
Returns the size of a file content. 

Arguments
A file!

Examples
; -------------------------------------------------------------------------
; www.red exists, bad.red does not
; -------------------------------------------------------------------------

>> size? %www.red
== 31
>> size? %bad.red
== none

top alphanumeric-index category-index



skip          type:  action!--    Cats: Series, String manipulation
The word skip moves the index of a series!.

Note: you can test the position of the index using index?.
Examples
red>> x: [1 2 3 4 5 6 7 8 9]
== [1 2 3 4 5 6 7 8 9]

red>> index? x
== 1

red>> skip x 3
== [4 5 6 7 8 9] ; Skip does not change the target series!

red>> x
== [1 2 3 4 5 6 7 8 9]

red>> x: skip x 3
== [4 5 6 7 8 9]

red>> x
== [4 5 6 7 8 9]

red>> index? x
== 4 ; Original position (1) + skip offset (3)

red>> x: skip x -1 ; Skipping backward is allowed
== [3 4 5 6 7 8 9]

red>> x
== [3 4 5 6 7 8 9]

red>> index? x
== 3

red>> x: skip x 100 ; Skip forward out of range moves to tail
== []

red>> index? x
== 10

red>> tail? x
== true

red>> x: skip x -100 ; Skip backward out of range moves to head
== [1 2 3 4 5 6 7 8 9]

red>> index? x
== 1

red>> head? x
== true

top alphanumeric-index category-index



slash          type:  char!--    Cats: Constants
A pre-defined char! value.

See char!

top alphanumeric-index category-index



sort          type:  action!--    Cats: Series, String manipulation
The word sort sorts a series!, modifying the original series!.  

The default order is ascending and the sort is by default case-insensitive.

The argument must be a series! type:
- block!
- string!
- vector!
etc.

Refinements
/case - perform a case-sensitive sort.
/reverse - reverse the sort order (descending instead of ascending)
/skip - treat the series! as fixed size records (groups of items).
Sorting is performed based on the value of the first item in
a group of items. The group size is specified as an integer!.
/part - sort only part of a series!.
We provide a length (a number!) or a position in the series!
/compare - we specify a comparator, which can be an offset integer!,
a block! or a function!.
/all - will force a group of items to be passed as a series! to
the compare function. You also will need /skip to specify the
size of such a group.
/stable - sort uses Quicksort as its default sorting algorithm.
Quicksort is very fast, but it is an unstable algorithm.
If you need stable sorting, add the /stable refinement, and it
will then use the Merge algorithm instead.
This issue is not significant for sorting simple series!.

Read more about sort algorithms here:
Wikipedia on sort algorithm
Examples
; -------------------------------------------------------------------------
; Sort some numbers ascending (changing the series! involved)
; -------------------------------------------------------------------------

red>> ages: [55 33 73 73 19]
== [55 33 73 73 19]

red>> sort ages
== [19 33 55 73 73]

red>> ages
== [19 33 55 73 73]

; -------------------------------------------------------------------------
; Sort some numbers descending
; -------------------------------------------------------------------------

red>> ages: [55 33 73 73 19]
== [55 33 73 73 19]

red>> sort/reverse ages
== [73 73 55 33 19]

red>> ages
== [73 73 55 33 19]

; -------------------------------------------------------------------------
; Sort strings (case-insensitive sort)
; -------------------------------------------------------------------------

red>> names: ["dog" "Ape" "Cat" "ant" "aardvark"]
== ["dog" "Ape" "Cat" "ant" "aardvark"]

red>> sort names
== ["aardvark" "ant" "Ape" "Cat" "dog"]

red>> names
== ["aardvark" "ant" "Ape" "Cat" "dog"]

; -------------------------------------------------------------------------
; Sort strings (case-insensitive sort)
; -------------------------------------------------------------------------

red>> names: ["dog" "Ape" "Cat" "ant" "aardvark"]
== ["dog" "Ape" "Cat" "ant" "aardvark"]

red>> sort/case names
== ["Ape" "Cat" "aardvark" "ant" "dog"]

red>> names
== ["Ape" "Cat" "aardvark" "ant" "dog"]

; -------------------------------------------------------------------------
; Sort on the first item of each group of 2 items (the name)
; -------------------------------------------------------------------------

red>> name-ages: ["Larry" 45 "Curly" 50 "Mo" 42]
== ["Larry" 45 "Curly" 50 "Mo" 42]

red>> sort/skip name-ages 2
== ["Curly" 50 "Larry" 45 "Mo" 42]

red>> name-ages
== ["Curly" 50 "Larry" 45 "Mo" 42]

; -------------------------------------------------------------------------
; Sort on a specific item (not the first which is default) of each group
; -------------------------------------------------------------------------

red>> name-ages: ["Larry" 45 "Curly" 50 "Mo" 42]
== ["Larry" 45 "Curly" 50 "Mo" 42]

red>> sort/skip/compare name-ages 2 2
== ["Mo" 42 "Larry" 45 "Curly" 50]

red>> name-ages
== ["Mo" 42 "Larry" 45 "Curly" 50]

; -------------------------------------------------------------------------
; Sort only a subset of the series! using a number
; -------------------------------------------------------------------------

red>> s: [8 7 6 5 4 3 2]
== [8 7 6 5 4 3 2]

red>> sort/part s 3
== [6 7 8 5 4 3 2] ; Only the first 3 items were sorted

red>> s
== [6 7 8 5 4 3 2]

; -------------------------------------------------------------------------
; Sort only a subset of the series! using a position
; -------------------------------------------------------------------------

red>> n: [9 8 7 6 5 4 3 2 1]
== [9 8 7 6 5 4 3 2 1]

red>> pos: skip n 4
== [5 4 3 2 1]

red>> sort/part n pos
== [6 7 8 9 5 4 3 2 1] ; Only the first 4 items were sorted

red>> n
== [6 7 8 9 5 4 3 2 1]

; -------------------------------------------------------------------------
; Using /compare to specify a function to compare 2 items
; -------------------------------------------------------------------------

red>> names: ["Larry" "Curly" "Mo" ]
== ["Larry" "Curly" "Mo"]

red>> sort/compare names function [a b] [a > b]
== ["Mo" "Larry" "Curly"]

red>> names
== ["Mo" "Larry" "Curly"]

red>> sort/compare names function [a b] [a < b]
== ["Curly" "Larry" "Mo"]

red>> names
== ["Curly" "Larry" "Mo"]

; -------------------------------------------------------------------------
; Specify which columns to compare using a path (e.g. /2)
; -------------------------------------------------------------------------

red>> names2: ["Larry" 45 "Curly" 50 "Mo" 42]
== ["Larry" 45 "Curly" 50 "Mo" 42]

red>> sort/skip/compare/all names2 2 function [a b][a/2 > b/2]
== ["Curly" 50 "Larry" 45 "Mo" 42] ; Sorted by descending age

red>> name-ages
== ["Curly" 50 "Larry" 45 "Mo" 42]

top alphanumeric-index category-index



source          type:  function!--    Cats: Documentation, Help & Debug
The word source shows the source code of a mezzanine word. 
Does not return a value.

A mezzanine word is a Red word! that is defined in terms of Red itself.

Has 1 parameter, the name of an existing Red word,
Examples
>> source rejoin
rejoin: func [
"Reduces and joins a block of values."
block [block!] "Values to reduce and join"
][
if empty? block: reduce block [return block]
append either series? first block [copy first block] [
form first block
] next block
]

top alphanumeric-index category-index



sp          type:  char!--    Cats: Constants
A pre-defined char! value.

See char!

top alphanumeric-index category-index



space          type:  char!--    Cats: Constants
A pre-defined char! value.

See char!

top alphanumeric-index category-index



spec-of          type:  function!--    Cats: Reflection
Returns the spec of a value that supports reflection. 

Arguments
A value of a type that supports reflection.


top alphanumeric-index category-index



split          type:  function!--    Cats: String manipulation
The word split breaks a string! into pieces using the provided delimiters.   
A block! is returned containing the individual pieces.

The arguments are:
a series - any-string! - the string to be split.
a delimiter - string! or char! - the delimiter
Note that the char! datatype has some common delimeters
predefined (such as 'newline', 'tab', 'space'. 'escape' etc.)
Examples
; -------------------------------------------------------------------------
; Split with a space
; -------------------------------------------------------------------------

red>> s1: "A few words"
== "A few words"

red>> split s1 " "
== ["A" "few" "" "" "" "" "" "words"]

; -------------------------------------------------------------------------
; Use the predefined constant "space"
; -------------------------------------------------------------------------

red>> split s1 space
== ["A" "few" "" "" "" "" "" "words"]

top alphanumeric-index category-index



split-path          type:  function!--    Cats: Directories, Files
Splits a file! or url! path. Returns a block containing path and 
target.

Arguments

A file! or a url!

Examples
; -------------------------------------------------------------------------
; Use split-path on a url, and a file
; -------------------------------------------------------------------------

red>> split-path http://www.red-lang.org/p/about.html
== [http://www.red-lang.org/p/ %about.html]

red>> split-path %data/personal/notes.txt
== [%data/personal/ %notes.txt]

top alphanumeric-index category-index



sqrt          type:  function!--    Cats: Math
USAGE:
SQRT number

DESCRIPTION:
Returns the square root of a number.
SQRT is a function! value.

ARGUMENTS:
number [number!]

RETURNS:
[float!]
; -------------------------------------------------------------------------
; sqrt
; -------------------------------------------------------------------------

>> sqrt 2.1
== 1.449137674618944
>> sqrt 16
== 4.0

top alphanumeric-index category-index



square-root          type:  native!--    Cats: Math
The word square-root returns the square-root of a number!.

Its argument must be a number! type.
Examples
; -------------------------------------------------------------------------
; Square-root of integer! gives a float!
; -------------------------------------------------------------------------

red>> square-root 16
4.0

; -------------------------------------------------------------------------
; Square-root of a float!
; -------------------------------------------------------------------------

red>> square-root 4.1
2.024845673131658

; -------------------------------------------------------------------------
; Square-root of a negative number (NaN = Not a Number)
; -------------------------------------------------------------------------

red>> square-root -9
1.#NaN

; -------------------------------------------------------------------------
; Square-root of a pair! (invalid operation))
; -------------------------------------------------------------------------

red>> square-root 22x33
*** Script error: square-root does not allow pair! for its value argument
*** Where: square-root

top alphanumeric-index category-index



stats          type:  native!--    Cats: System Related
The word stats returns interpreter statistics, including 
memory management data.

Refinements
/show - not yet implemented
/info - more detailed data
Examples
; -------------------------------------------------------------------------
; Basic stats
; -------------------------------------------------------------------------

red>> stats
== 86605824

; -------------------------------------------------------------------------
; More detailed stats (Can be a large block!, hence the ...)
; -------------------------------------------------------------------------

red>> print mold stats/info
== [[[9999 1 10000] [9999 1 10000] [9999 1 10000] [9999 1 10000] [...

top alphanumeric-index category-index



stop-reactor          type:  function!--    Cats: Reactivity
USAGE:
STOP-REACTOR face

DESCRIPTION:
STOP-REACTOR is a function! value.

ARGUMENTS:
face [object!]

REFINEMENTS:
/deep =>
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



strict-equal?          type:  native!--    Cats: Comparison
The word strict-equal? returns true if two values are equal
and are of the same datatype!, otherwise returns false.

When comparing strings lowercase is considered not equal to uppercase.
Examples
red>> strict-equal? 12 12.0
== false

red>> strict-equal? "abc" "abc"
== true

red>> strict-equal? "abC" "ABC"
== false

top alphanumeric-index category-index



string!          type:  datatype!--    Cats: Datatypes
The datatype! string! represents a series! type containing char!.
For string functions (such as substring etc), we use the series functions, here.
(Awaiting additional documentation by red-by-example team.)
Examples
; -------------------------------------------------------------------------
; Some examples
; -------------------------------------------------------------------------

red>> str: "abcdefg"
== "abcdefg"
;Using { } allows a string to spread over several lines - spaces and newlines are significant
red>> s: { a two-line
string}
red>> str/3
== #"c" ; Representation of a single character in Red

top alphanumeric-index category-index



string?          type:  function!--    Cats: Type Checking
The word string? returns true if its argument is
a string!, otherwise false.

Its argument can be of any type.
Examples
; -------------------------------------------------------------------------
; Test a string!
; -------------------------------------------------------------------------

red>> string? "abc"
true

; -------------------------------------------------------------------------
; Test a char!
; -------------------------------------------------------------------------

red>> string? #"A"
false

; -------------------------------------------------------------------------
; Test a number!
; -------------------------------------------------------------------------

red>> string? 12.34
false

top alphanumeric-index category-index



subtract          type:  action!--    Cats: Math
The word subtract subtracts the second value from the first.
It is equivalent of the infix operator -.

It has 2 arguments, which can be of these types:
number! char! pair! tuple! vector!
Examples
red>> subtract 3.4 2
== 1.4

red>> v: make vector! [2 3 4]
== make vector! [2 3 4]

red>> v2: make vector! [10 100 200]
== make vector! [10 100 200]

red>> subtract v v2
== make vector! [-8 -97 -196]

red>> subtract 20x10 3x3
== 17x7

red>> subtract 10 3x3
*** Script error: subtract does not allow pair for its value2 argument
*** Where: subtract

red>> subtract 3x3 10
== -7x-7

top alphanumeric-index category-index



suffix?          type:  function!--    Cats: Directories, Files
The word suffix? returns the extension of a file!, 
the suffix of a url!, otherwise returns none.

Note that when a suffix is found, a file! type is returned.

Its single argument can be:
file! url! string!
Examples
; -------------------------------------------------------------------------
; File with extension (The % is used in literal files)
; -------------------------------------------------------------------------

red>> suffix? %myfile.txt
%.txt

; -------------------------------------------------------------------------
; File without extension
; -------------------------------------------------------------------------

red>> suffix? %myfile
none

; -------------------------------------------------------------------------
; URL with suffix
; -------------------------------------------------------------------------

red>> suffix? http://www.place.org/info.html
%.html

; -------------------------------------------------------------------------
; URL without suffix
; -------------------------------------------------------------------------

red>> suffix? http://www.google.com/
none

; -------------------------------------------------------------------------
; File with extension as a string!
; -------------------------------------------------------------------------

red>> suffix? "data.txt"
%.txt

top alphanumeric-index category-index



sum          type:  function!--    Cats: Math
USAGE:
SUM values

DESCRIPTION:
Returns the sum of all values in a block.
SUM is a function! value.

ARGUMENTS:
values [block! vector! paren! hash!]
; -------------------------------------------------------------------------
; sum - note diffent types used
; -------------------------------------------------------------------------

>> sum [1 2 3 4 5]
== 15
>> sum [1.2 3.4]
== 4.6
>> sum [3 4 5x5]
== 12x12

top alphanumeric-index category-index



swap          type:  action!--    Cats: Series, String manipulation
The word swap swaps elements between two series! or the same series!.  
It modifies both arguments.

The 2 arguments must be of type series!
Examples
; -------------------------------------------------------------------------
; Create 2 series to work with (different lengths)
; -------------------------------------------------------------------------

red>> s1: [1 2 3 4 5 6]
== [1 2 3 4 5 6]

red>> s2: [100 200 300 400]
== [100 200 300 400]

red>> swap s1 s2 ; Swap first elements
== [100 2 3 4 5 6]

red>> s1
== [100 2 3 4 5 6] ; s1 was changed

red>> s2
== [1 200 300 400] ; s2 also changed

; -------------------------------------------------------------------------
; Swap within same series; arg 1 is element 1; arg 2 is element 100
; -------------------------------------------------------------------------

red>> ser: [ 1 2 3 4 5 100 200 300 400]
== [1 2 3 4 5 100 200 300 400]

red>> swap ser find ser 100
== [100 2 3 4 5 1 200 300 400]

; -------------------------------------------------------------------------
; Also string!s are series!!
; -------------------------------------------------------------------------

red>> swap "ABC" "xyz" ; Swap first characters of each string
== "xBC"

; -------------------------------------------------------------------------
; Swap in the middle of some series!
; -------------------------------------------------------------------------

red>> sa: [22 11 33 55]
== [22 11 33 55]

red>> sb: [105 101 107 109]
== [105 101 107 109]

red>> swap find sa 33 find sb 101
== [101 55]

red>> sa
== [22 11 101 55]

red>> sb
== [105 33 107 109]

top alphanumeric-index category-index



switch          type:  native!--    Cats: Conditional branching
The word switch chooses a block! based on a value.  

We provide a value (which can be an expression of any type), then a
series of block!s, each prefixed with a value.

The block associated with the matching value is evaluated.
The prefixed values are not evaluated (Note that differing types are allowed).

The value of the last evaluation in the matched block is returned.

Refinements
/default - allows us to specify a default block! at
the bottom of the switch, which is executed
when no value matches
Examples
; -------------------------------------------------------------------------
; We try to match on different datatypes here
; -------------------------------------------------------------------------


switch 23.77.44 [
1 [print "1: integer"]
23.77.44 [print "23.77.44: a tuple"]
"India" [print "India: string"
country: true]
]
23.77.44: a tuple

; -------------------------------------------------------------------------
; Using the /default refinement where nothing matches with "China"
; -------------------------------------------------------------------------


item: "China"
switch/default item [
1 [print "1: integer"]
23.77.44 [print "23.77.44: a tuple"]
"India" [print "India: string"
country: true]
] [
print "No match"
]
No match

top alphanumeric-index category-index



tab          type:  char!--    Cats: Constants
A pre-defined char! value.

See char!

top alphanumeric-index category-index



tag!          type:  datatype!--    Cats: Datatypes
This datatype! provides a literal way of expressing items enclosed
in '<' and '>'. It is a type of series. There are also the related
to-tag and tag? functions.

Examples
; -------------------------------------------------------------------------
; Create a tag! type, explore it.
; -------------------------------------------------------------------------

>> t: <picture 100 200>
== <picture 100 200>
; Examine its type
>> type? t
== tag!

; Tag as series:
>> first t
== #"p"
>> append t " square"
== <picture 100 200 square>

top alphanumeric-index category-index



tag?          type:  function!--    Cats: Type Checking
This function returns true if its argument is an tag!  datatype!, 
otherwise false.

Arguments

Its single argument can be anytype!.

Examples
; -------------------------------------------------------------------------
; explore tag?
; -------------------------------------------------------------------------

>> t:
==
>> tag? t
== true
>> tag? ""
== false


top alphanumeric-index category-index



tail          type:  action!--    Cats: Series, String manipulation
The word tail can be used to set a series! index right
after the last item in the series!.

The word tail? can be used to test if a series! is at tail.

The word index? can be used to obtain the current index.
Examples
red>> x: [1 2 3 4 5]
== [1 2 3 4 5]

red>> head? x
== true

red>> index? x
== 1

red>> x: tail x
== []

red>> tail? x
== true

red>> index? x
== 6 ; Note that the index is one beyond the last element!

top alphanumeric-index category-index



tail?          type:  action!--    Cats: Series, String manipulation
The word tail? tests if a series! is at tail position; 
it returns true if at tail or false otherwise.

The word index? can be used to obtain the current index.
Examples
red>> x: [1 2 3 4 5]
== [1 2 3 4 5]

red>> head? x
== true

red>> index? x
== 1

red>> x: tail x
== []

red>> tail? x
== true

red>> index? x
== 6 ; Note that the index is one beyond the last element!

top alphanumeric-index category-index



take          type:  action!--    Cats: Series
The word take removes and returns one or more elements of a series!. 

Using append with take and its /tail refinement lets us use a series!
as a stack or queue.

Arguments
The single argument is a series! or none!

Refinements
/part - specifies a length or end position.
Supply a length (a number!) or a position in a series!
/deep - copy nested series values.
/last - take from from the tail end.
Examples
; -------------------------------------------------------------------------
; Examples of take, and some refinements
; -------------------------------------------------------------------------

red>> s: [11 22 33 44 55]

red>> take s
== 11

red>> s
== [22 33 44 55]

red>> s: [11 22 33 44 55]
== [11 22 33 44 55]

red>> take/last s
== 55

red>> s
== [11 22 33 44]

red>> s: [11 22 33 44 55]
== [11 22 33 44 55]

red>> take/part s 3
== [11 22 33]

red>> s
== [44 55]

top alphanumeric-index category-index



tan          type:  function!--    Cats: Math
To do by red-by-example team ...


top alphanumeric-index category-index



tangent          type:  native!--    Cats: Math
The word tangent returns the trigonometric tangent of a number!
of degrees.

It has one numeric parameter.

Refinements:
/radians : expects the input value in radians;
without refinement expects the input value in degrees.
Examples
tangent 45
== 1.0

tangent 60 * 1.1
== 2.246036773904216

tangent/radians 1.05
== 1.74331530998317

top alphanumeric-index category-index



third          type:  function!--    Cats: Series, String manipulation
The word third returns the third value in a series! (also string!s).

The argument can be one of:
series! tuple! pair!

If there is no third item, none is returned.
Examples
; -------------------------------------------------------------------------
; Third of block
; -------------------------------------------------------------------------

red>> third [2 3 4 5]
== 4

; -------------------------------------------------------------------------
; Third of a string is a character type
; -------------------------------------------------------------------------

red>> third "ABCDE"
== #"C"

; -------------------------------------------------------------------------
; Third of a tuple
; -------------------------------------------------------------------------

red>> third 22.33.44.55
== 44

; -------------------------------------------------------------------------
; No third here
; -------------------------------------------------------------------------

red>> third[44]
== none

top alphanumeric-index category-index



throw          type:  native!--    Cats: Conditional branching, Error
Throws control to a catch. Note that catch and throw are mainly 
intended for creating new control structures, and are not the main
exception-handling functions. For this, look at attempt, try,
cause-error error?, and error!.

For throw examples, look at the entry for catch.

Arguments

The single argument value, can be any type, and will be the value returned
from the matching catch.

Refinements
/name - Throws to a named catch. We supply a word.

top alphanumeric-index category-index



time!          type:  datatype!--    Cats: Datatypes
The  Time! datatype! lets us express an amount of time in hours, minutes, 
seconds, and subseconds. Both positive and negative times are permitted.
Colons separate items, apart from subseconds, which use a decimal point.

Times are stored in a standard form, irrespective of how they are entered.
(Thus, 59 minutes and 63 seconds are stored as 1 hour, 0 minutes, and 3 seconds.)

The refinements /hour /minute /second can be used to get part of a time.

Times can be compared, and used in calculations where a time result is meaningful.
For example, we can add two times, but not multiply them.

The to-time function can be used to convert other values into a time!.


Examples
; -------------------------------------------------------------------------
; Create some times, work with them.
; -------------------------------------------------------------------------


; Create times
>> t1: 3:4:58
== 3:04:58
>> t2: 24:0:63
== 24:01:03
>> t3: 3:0.95
== 0:03:00.950000001

; Refinement
>> t1/second
== 58.0

; Comparison
>> t1 > t2
== false

; Calculations
>> t1 * 2.9
== 8:56:24.2
>> t1 + t2
== 27:06:01

>> t1 * t2
*** Script Error: incompatible argument for multiply of time!
*** Where: *

; Use of to-time function
>> to-time [11 22 33]
== 11:22:33
>> to-time [11 22 61]
== 11:23:01
>> to-time "12:24"
== 12:24:00


top alphanumeric-index category-index



time?          type:  function!--    Cats: Type Checking
The word time? returns true if the value is a time!, 
otherwise false.

Arguments
Has one argument, which can be of any type.
Examples
; -------------------------------------------------------------------------
; Show usage here
; -------------------------------------------------------------------------

red>> time? 3:15
== true

red>> type? 3:15
== time!

red>> time? 3.15
== false

red>> type? 3.15
== float!

red>> t: 3:45
== 3:45:00.0

red>> time? t
== true

top alphanumeric-index category-index



to          type:  action!--    Cats: Casting Types, Conversion
The word to converts a value to a specified datatype!.  
Only specific conversions are allowed.

Arguments:
type - a datatype! name. Note that this name can be the result of an evaluation.
spec - the attributes of the new value. Often, this is simply the value itself.
Examples
; -------------------------------------------------------------------------
; Do some simple conversions
; -------------------------------------------------------------------------

red>> to integer! 2.333
2

red>> to string! 234
"234"

red>> to integer! "23456"
23456

red>> to integer! "33"
== 33

red>> to set-word! "foo"
== foo:

red>> to word! "bar"
== bar

; -------------------------------------------------------------------------
; Compute the new type
; -------------------------------------------------------------------------

red>> affect: true
true

red>> to either affect [float!] [string!] 567
567.0

top alphanumeric-index category-index



to-binary          type:  function!--    Cats: Bases of Numbers, Conversion
USAGE:
TO-BINARY value

DESCRIPTION:
Convert to binary! value.
TO-BINARY is a function! value.

ARGUMENTS:
value

Equivalent to using: to binary!
See binary!
; -------------------------------------------------------------------------
; to-binary with various types
; -------------------------------------------------------------------------

>> to-binary 15
== #{0000000F}
>> to-binary 2.3
== #{4002666666666666}
>> to-binary "ABCDE"
== #{4142434445}

top alphanumeric-index category-index



to-bitset          type:  function!--    Cats: Bit manipulation, Conversion
USAGE:
TO-BITSET value

DESCRIPTION:
Convert to bitset! value.
TO-BITSET is a function! value.

ARGUMENTS:
value

Equivalent to using: to bitset!
See bitset!

; -------------------------------------------------------------------------
; to-bitset example:
; -------------------------------------------------------------------------

>> to-bitset #"A"
== make bitset! #{000000000000000040}


top alphanumeric-index category-index



to-block          type:  function!--    Cats: Conversion
USAGE:
TO-BLOCK value

DESCRIPTION:
Convert to block! value.
TO-BLOCK is a function! value.

ARGUMENTS:
value

Equivalent to using: to block!
See block!
; -------------------------------------------------------------------------
; to-block
; -------------------------------------------------------------------------

to-block 12.34
== [12.34]
>> to-block [12.34]
== [12.34]
>> to-block (1 2 3 4)
== [4]

top alphanumeric-index category-index



to-char          type:  function!--    Cats: Conversion
USAGE:
TO-CHAR value

DESCRIPTION:
Convert to char! value.
TO-CHAR is a function! value.

ARGUMENTS:
value

Equivalent to using: to char!
See char!
; -------------------------------------------------------------------------
; to-char with various types
; -------------------------------------------------------------------------

>> to-char 65
== #"A"
>> to-char "A" ;-- NB "A" is a string type
== #"A"
>> to-char "CAT" ;-- first char from string of chars
== #"C"

top alphanumeric-index category-index



to-date          type:  function!--    Cats: Conversion, Date/Time
USAGE:
TO-DATE value

DESCRIPTION:
Convert to date! value.
TO-DATE is a function! value.

ARGUMENTS:
value

Equivalent to using: to date!
See date!
; -------------------------------------------------------------------------
; to-date
; -------------------------------------------------------------------------

>> to-date [3 5 2022]
== 3-May-2022

top alphanumeric-index category-index



to-email          type:  function!--    Cats: Conversion, Network, URL/Internet
Converts a value to an email! type.

Arguments

It takes a single value.

Examples
; -------------------------------------------------------------------------
; Do some conversions to email!
; -------------------------------------------------------------------------


; String
>> to-email "a@b.c"
== a@b.c

; Block
>> to-email [a @b.c]
== a@b.c
; and confirm the type
>> type? to-email [a @b.c]
== email!

top alphanumeric-index category-index



to-file          type:  function!--    Cats: Conversion, Files
USAGE:
TO-FILE value

DESCRIPTION:
Convert to file! value.
TO-FILE is a function! value.

ARGUMENTS:
value

Equivalent to using: to file!
See file!
; -------------------------------------------------------------------------
; to-file
; -------------------------------------------------------------------------

>> f: "my-name.txt"
== "my-name.txt"
>> to-file f
== %my-name.txt

top alphanumeric-index category-index



to-float          type:  function!--    Cats: Conversion, Math
USAGE:
TO-FLOAT value

DESCRIPTION:
Convert to float! value.
TO-FLOAT is a function! value.

ARGUMENTS:
value

Equivalent to using: to float!
See float!
; -------------------------------------------------------------------------
; to-float, various types
; -------------------------------------------------------------------------

>> f: "12.34" ;-- string type
== "12.34"
>> to-float f
== 12.34
>> to-float 123 ;-- integer
== 123.0

top alphanumeric-index category-index



to-get-path          type:  function!--    Cats: Conversion
USAGE:
TO-GET-PATH value

DESCRIPTION:
Convert to get-path! value.
TO-GET-PATH is a function! value.

ARGUMENTS:
value

Equivalent to using: to get-path!
See get-path!
; -------------------------------------------------------------------------
; to-get-path
; -------------------------------------------------------------------------

>> g: [aa bb cc]
== [aa bb cc]
>> to-get-path g
== :aa/bb/cc

>> g: "aa bb cc"
== "aa bb cc"
>> to-get-path g
== :aa/bb/cc


top alphanumeric-index category-index



to-get-word          type:  function!--    Cats: Conversion, Word Manipulation
USAGE:
TO-GET-WORD value

DESCRIPTION:
Convert to get-word! value.
TO-GET-WORD is a function! value.

ARGUMENTS:
value

Equivalent to using: to get-word!
See get-word!
; -------------------------------------------------------------------------
; to-get-word
; -------------------------------------------------------------------------

>> to-get-word "abc"
== :abc

top alphanumeric-index category-index



to-hash          type:  function!--    Cats: Conversion, Series
USAGE:
TO-HASH value

DESCRIPTION:
Convert to hash! value.
TO-HASH is a function! value.

ARGUMENTS:
value
(Awaiting additional documentation by red-by-example team.)


top alphanumeric-index category-index



to-hex          type:  native!--    Cats: Bases of Numbers, Conversion
The word to-hex converts an integer! to a hexadecimal 
value, with a leading # and leading zeroes.

Its argument is an integer!.

Refinements
/size - an integer! specifying the number of
hexadecimal digits in the result.
No errors result if a small size value
removes significant parts of the result.
Examples
; -------------------------------------------------------------------------
; Conversions of positive and negative integer!s
; -------------------------------------------------------------------------

red>> to-hex 64
#00000040

red>> to-hex -1
#FFFFFFFF

red>> to-hex 2 ** 31
== #80000000 ; Left most bit (= sign bit) is set

; -------------------------------------------------------------------------
; Limit digits with /size (from the right)
; -------------------------------------------------------------------------

red>> to-hex/size 64 4
#0040

top alphanumeric-index category-index



to-image          type:  function!--    Cats: Conversion, GUI: VID, View
USAGE:
TO-IMAGE value

DESCRIPTION:
Convert to image! value.
TO-IMAGE is a function! value.

ARGUMENTS:
value
(Awaiting additional documentation by red-by-example team.)

See image! datatype.

top alphanumeric-index category-index



to-integer          type:  function!--    Cats: Conversion, Math
USAGE:
TO-INTEGER value

DESCRIPTION:
Convert to integer! value.
TO-INTEGER is a function! value.

ARGUMENTS:
value

Equivalent to using: to integer!
See integer!
; -------------------------------------------------------------------------
; to-integer with various types
; -------------------------------------------------------------------------

>> to-integer 2.3
== 2
>> to-integer 2.9
== 2
>> to-integer #"A" ;-- char!
== 65
>> to-integer "ABC" ;-- error in string!
*** Script Error: cannot MAKE/TO integer! from: "ABC"
>> to-integer "123" ;-- allowed string!
== 123

top alphanumeric-index category-index



to-issue          type:  function!--    Cats: Conversion
USAGE:
TO-ISSUE value

DESCRIPTION:
Convert to issue! value.
TO-ISSUE is a function! value.

ARGUMENTS:
value

Equivalent to using: to issue!
See issue!

top alphanumeric-index category-index



to-lit-path          type:  function!--    Cats: Conversion
USAGE:
TO-LIT-PATH value

DESCRIPTION:
Convert to lit-path! value.
TO-LIT-PATH is a function! value.

ARGUMENTS:
value

Equivalent to using: to lit-path!
See lit-path!
; -------------------------------------------------------------------------
; lit-path
; -------------------------------------------------------------------------

>> to-lit-path [aa bb cc]
== 'aa/bb/cc

top alphanumeric-index category-index



to-lit-word          type:  function!--    Cats: Conversion, Word Manipulation
USAGE:
TO-LIT-WORD value

DESCRIPTION:
Convert to lit-word! value.
TO-LIT-WORD is a function! value.

ARGUMENTS:
value

The equivalent of: to lit-word!

See lit-word!

; -------------------------------------------------------------------------
; to-lit-word
; -------------------------------------------------------------------------

>> to-lit-word "abc"
== 'abc
>> to-lit-word first [abc]
== 'abc

top alphanumeric-index category-index



to-local-date          type:  function!--    Cats: Conversion, Date/Time
USAGE:
TO-LOCAL-DATE date

DESCRIPTION:
Returns the date with local zone.
TO-LOCAL-DATE is a function! value.

ARGUMENTS:
date [date!]

RETURNS:
[date!]

See date!
; -------------------------------------------------------------------------
; to-local-date - note added zone time-difference
; -------------------------------------------------------------------------

>> to-local-date 3-June-2020
== 3-Jun-2020/1:00:00+01:00

top alphanumeric-index category-index



to-local-file          type:  native!--    Cats: Conversion, Files
The word to-local-file converts standard, system independent Red 
file paths to the file format used by the local operating system.

The path argument must be a file! or a string!.

Refinements
/full - prepends current dir for full path (for relative paths only)
Examples
; -------------------------------------------------------------------------
; Windows - using Red file!
; -------------------------------------------------------------------------

red>> to-local-file %/c/data.txt
"c:\data.txt"

; -------------------------------------------------------------------------
; Windows - using a string!
; -------------------------------------------------------------------------

red>> to-local-file "/c/data.txt"
"c:\data.txt"

; -------------------------------------------------------------------------
; Windows - with /full refinement
; -------------------------------------------------------------------------

red>> what-dir
== %/E/Websites/Red-by-Example/auto-v5/ ; Current directory

red>> to-local-file/full %data.txt ; Relative path
== "E:\Websites\Red-by-Example\auto-v5\data.txt"

top alphanumeric-index category-index



to-logic          type:  function!--    Cats: Boolean, Conversion
USAGE:
TO-LOGIC value

DESCRIPTION:
Convert to logic! value.
TO-LOGIC is a function! value.

ARGUMENTS:
value

Returns true for any value except for false and none.
Equivalent to using: to logic!
See logic!

; -------------------------------------------------------------------------
; to-logic
; -------------------------------------------------------------------------

>> find "ABCDE" "X" ;-- normal find usage
== none
>> find "ABCDE" "B"
== "BCDE"
;-- we might only want a there/missing result
>> to-logic find "ABCDE" "X"
== false
>> to-logic find "ABCDE" "B"
== true

top alphanumeric-index category-index



to-map          type:  function!--    Cats: Conversion, Series
USAGE:
TO-MAP value

DESCRIPTION:
Convert to map! value.
TO-MAP is a function! value.

ARGUMENTS:
value

Equivalent to using: to map!
See map!
; -------------------------------------------------------------------------
; to-map
; -------------------------------------------------------------------------

>> to-map [a 1 'b 2 "c" 3]
== #(
a: 1
b: 2
"c" 3
)

top alphanumeric-index category-index



to-none          type:  function!--    Cats: Conversion
USAGE:
TO-NONE value

DESCRIPTION:
Convert to none! value.
TO-NONE is a function! value.

ARGUMENTS:
value
(Awaiting additional documentation by red-by-example team.)

Equivalent to using: to none!
See none!


top alphanumeric-index category-index



to-pair          type:  function!--    Cats: Conversion
USAGE:
TO-PAIR value

DESCRIPTION:
Convert to pair! value.
TO-PAIR is a function! value.

ARGUMENTS:
value

Equivalent to using: to pair!
See pair!
; -------------------------------------------------------------------------
; to-pair with various types
; -------------------------------------------------------------------------

>> to-pair 22
== 22x22
>> to-pair [22 33]
== 22x33

top alphanumeric-index category-index



to-paren          type:  function!--    Cats: Conversion
USAGE:
TO-PAREN value

DESCRIPTION:
Convert to paren! value.
TO-PAREN is a function! value.

ARGUMENTS:
value

Equivalent to using: to paren!
See paren!
; -------------------------------------------------------------------------
; to-paren with various types
; -------------------------------------------------------------------------

>> to-paren "ABC"
== (ABC)
>> to-paren [3 + 4]
== (3 + 4)


top alphanumeric-index category-index



to-path          type:  function!--    Cats: Conversion
USAGE:
TO-PATH value

DESCRIPTION:
Convert to path! value.
TO-PATH is a function! value.

ARGUMENTS:
value

Equivalent to using: to path!
See path!
; -------------------------------------------------------------------------
; to-path with various types
; -------------------------------------------------------------------------

>> to-path [a b c]
== a/b/c
>> to-path "aa bb cc"
== aa/bb/cc

top alphanumeric-index category-index



to-percent          type:  function!--    Cats: Conversion
USAGE:
TO-PERCENT value

DESCRIPTION:
Convert to percent! value.
TO-PERCENT is a function! value.

ARGUMENTS:
value

Equivalent to using: to percent!
See percent!
; -------------------------------------------------------------------------
; to-percent with various types
; -------------------------------------------------------------------------

>> to-percent 0.75
== 75%
>> to-percent 33
== 3300%

top alphanumeric-index category-index



to-red-file          type:  function!--    Cats: Conversion, Files
The word to-red-file converts a local file system path to Red's 
standard machine independent path format.

The argument can be:
- a Red file!
- a string!.

Note that a Red file path - preceded by % - cannot contain a colon (:)
as used in Windows paths, though it can contain \.
The string argument can contain a colon (:).
Examples
; -------------------------------------------------------------------------
; Convert a file containing backslashes
; -------------------------------------------------------------------------

red>> to-red-file %\data\notes.txt
%/data/notes.txt

; -------------------------------------------------------------------------
; Convert a Windows file in a string
; -------------------------------------------------------------------------

red>> to-red-file "C:\data\notes.txt"
%/C/data/notes.txt

top alphanumeric-index category-index



to-refinement          type:  function!--    Cats: Conversion
USAGE:
TO-REFINEMENT value

DESCRIPTION:
Convert to refinement! value.
TO-REFINEMENT is a function! value.

ARGUMENTS:
value

Equivalent to using: to refinement!
See refinement!
; -------------------------------------------------------------------------
; to-refinement
; -------------------------------------------------------------------------

>> r: /abcd
== /abcd
>> r: to-refinement r
== /abcd
>> type? r
== refinement!

top alphanumeric-index category-index



to-set-path          type:  function!--    Cats: Conversion
USAGE:
TO-SET-PATH value

DESCRIPTION:
Convert to set-path! value.
TO-SET-PATH is a function! value.

ARGUMENTS:
value

Equivalent to using: to set-path!
See set-path!
; -------------------------------------------------------------------------
; to-set-path
; -------------------------------------------------------------------------

>> to-set-path 'abc
== abc:

top alphanumeric-index category-index



to-set-word          type:  function!--    Cats: Conversion, Word Manipulation
USAGE:
TO-SET-WORD value

DESCRIPTION:
Convert to set-word! value.
TO-SET-WORD is a function! value.

ARGUMENTS:
value

Equivalent to using: to set-word!
See set-word!
; -------------------------------------------------------------------------
; to-set-word
; -------------------------------------------------------------------------

>> to-set-word 'abc
== abc:

top alphanumeric-index category-index



to-string          type:  function!--    Cats: Conversion, String manipulation
USAGE:
TO-STRING value

DESCRIPTION:
Convert to string! value.
TO-STRING is a function! value.

ARGUMENTS:
value

Equivalent to using: to string!
See string!
; -------------------------------------------------------------------------
; to-string with various types
; -------------------------------------------------------------------------

>> to-string 123
== "123"
>> to-string #"A"
== "A"
>> to-string [1 2 3]
== "123"

top alphanumeric-index category-index



to-tag          type:  function!--    Cats: Conversion
Converts its single argument to  a tag!.

Arguments

A single argument, of any type.

Examples

; -------------------------------------------------------------------------
; Explore to-tag, with several types of arguments.
; -------------------------------------------------------------------------

; integer!
>> to-tag 1234
== <1234>
>> v: 3 + 5
== 8
>> to-tag v
== <8>

; string!
>> to-tag "the cat"
==
>> block!
to-tag [a b]
==


top alphanumeric-index category-index



to-time          type:  function!--    Cats: Conversion, Date/Time
Converts a value to a time!.

Arguments

A single value.

Examples
>> to-time [11 22 33]
== 11:22:33
>> to-time [11 22 61]
== 11:23:01
>> to-time "12:24"
== 12:24:00
>> t1 + t2
== 27:06:01

top alphanumeric-index category-index



to-tuple          type:  function!--    Cats: Conversion
USAGE:
TO-TUPLE value

DESCRIPTION:
Convert to tuple! value.
TO-TUPLE is a function! value.

ARGUMENTS:
value

Equivalent to using: to tuple!
See tuple!
; -------------------------------------------------------------------------
; to-tuple
; -------------------------------------------------------------------------

>> to-tuple "12.34.88"
== 12.34.88

top alphanumeric-index category-index



to-typeset          type:  function!--    Cats: Conversion, Datatypes
USAGE:
TO-TYPESET value

DESCRIPTION:
Convert to typeset! value.
TO-TYPESET is a function! value.

ARGUMENTS:
value

Equivalent to using: to typeset!
See typeset!
; -------------------------------------------------------------------------
; to-typeset
; -------------------------------------------------------------------------

>> num-type!: to-typeset [integer! percent! float!]
== make typeset! [integer! float! percent!]
>> type? num-type!
== typeset!

top alphanumeric-index category-index



to-unset          type:  function!--    Cats: Conversion
USAGE:
TO-UNSET value

DESCRIPTION:
Convert to unset! value.
TO-UNSET is a function! value.

ARGUMENTS:
value
(Awaiting additional documentation by red-by-example team.)

See unset!

top alphanumeric-index category-index



to-url          type:  function!--    Cats: Conversion, URL/Internet
USAGE:
TO-URL value

DESCRIPTION:
Convert to url! value.
TO-URL is a function! value.

ARGUMENTS:
value

Equivalent to using: to url!
See url!
; -------------------------------------------------------------------------
; to-url
; -------------------------------------------------------------------------

>> to-url [aa bb cc]
== aa://bb/cc

top alphanumeric-index category-index



to-UTC-date          type:  function!--    Cats: Conversion, Date/Time
USAGE:
TO-UTC-DATE date

DESCRIPTION:
Returns the date with UTC zone.
TO-UTC-DATE is a function! value.

ARGUMENTS:
date [date!]

RETURNS:
[date!]

See date!
; -------------------------------------------------------------------------
; to-UTC-date
; -------------------------------------------------------------------------

;-- I'm in the UK, British Summertime, my watch says 9:32 a.m
;-- This time is offset from UTC time by 1 hour:
>> to-UTC-date now
== 30-May-2019/8:32:21

top alphanumeric-index category-index



to-word          type:  function!--    Cats: Conversion, Word Manipulation
USAGE:
TO-WORD value

DESCRIPTION:
Convert to word! value.
TO-WORD is a function! value.

ARGUMENTS:
value

Equivalent to using: to word!
See word!
; -------------------------------------------------------------------------
; to-word
; -------------------------------------------------------------------------

>> w: to-word 'aaa
== aaa
>> w
== aaa
>> type? w
== word!

top alphanumeric-index category-index



trim          type:  action!--    Cats: String manipulation
word trim removes white space (tabs and spaces) from a string! or none 
from a block! or object!. The value of the argument is altered.

The argument can be one of: series! object! error! map!

Refinements
/head - Removes only from the head.
/tail - Removes only from the tail.
/auto - Auto indents lines relative to first line.
/lines - Removes all line breaks and extra spaces.
/all - Removes all whitespace (but not line breaks).
/with - Same as /all, but removes characters in a 'with' argument we supply.
It must be one of: char! string! integer!
Examples
; -------------------------------------------------------------------------
; Basic trim.
; -------------------------------------------------------------------------

red>> str: " some text "
== " some text "

red>> trim str ; Both head and tail are trimmed
== "some text"

red>> str
== "some text" ; str was altered by trim

; -------------------------------------------------------------------------
; Multiple lines of text - enclosed in { }
; -------------------------------------------------------------------------

red>> str: {Four lines
{ of varying levels
{ of
{ indentation.}
== {Four lines^/ of varying levels^/ of^/ indentation.}

red>> trim str ; ^/ means a newline
== {Four lines^/of varying levels^/of^/indentation.}

; -------------------------------------------------------------------------
; Trim a block! - NB reduce evaluates every element in a block
; -------------------------------------------------------------------------

red>> blk: [none none 3 none]
== [none none 3 none]

red>> trim blk
== [none none 3 none] ; Because elements are not yet evaluated

red>> blk
== [none none 3 none] ; Trim did not alter the block

red>> trim reduce blk
== [3] ; Now trim worked succesfully!

; -------------------------------------------------------------------------
; /head - trim head only
; -------------------------------------------------------------------------

red>> trim/head " AAA "
== "AAA "

; -------------------------------------------------------------------------
; /tail - trim tail only
; -------------------------------------------------------------------------

red>> trim/tail " AAA "
== " AAA"

; -------------------------------------------------------------------------
; /lines - NB last line has line break at end
; -------------------------------------------------------------------------

red>> str: { Two lines
{ of text
{ }
== " Two lines ^/ of text^/ "

red>> trim/lines str
== "Two lines of text" ; Multiple spaces and line breaks are gone

; -------------------------------------------------------------------------
; /all - remove all space
; -------------------------------------------------------------------------

red>> trim/all " some text "
== "sometext"

; -------------------------------------------------------------------------
; /with - Note that spaces are not removed automatically
; -------------------------------------------------------------------------

red>> str: "some extra-characters,, to use"
== "some extra-characters,, to use"

red>> trim/with str ",-"
== "some extracharacters to use" ; , and - removed

red>> str: "some extra-characters,, to use"
== "some extra-characters,, to use"

red>> trim/with str ",- "
== "someextracharacterstouse" ; Now also spaces removed

top alphanumeric-index category-index



true          type:  logic!--    Cats: Boolean, Constants
The word true has the logical value "true" 
and its datatype! is logic!

Logical values are produced from various comparisons.

The logic! type also provides:
false, no, off, on, true, yes
Examples
3 = 3.0
== true

3 == 3.0
== false

3 = 4
== false

"abc" = "abc"
== true

"ABC" = "abc"
== true

if 4 > 3 [print "it is"]
-- it is

a: true
== true

b: 4 > 3
== true

top alphanumeric-index category-index



try          type:  native!--    Cats: Error
Tries to evaluate a block, similar to do. The value of the block is
returned, but if an error! occurs, the block is abandoned, and an
error value is returned.

Normally, the error is displayed, but we can intercept it with a
function to prevent the display. Often, the error? function is
used for this. We can also access the returned error! object
to get details of the error.

Note that try is concerned with error-handling, and should not
be used with catch and throw, which are intended for building
control structures.

For other error/exception-handling words, look at the related entries
for attempt, cause-error, error?, and the error! type.


Arguments
Its single argument is a block!

Refinements
/all - detects also break, continue, return, exit
and throw exceptions.

Examples
; -------------------------------------------------------------------------
; try, cause-error, and error? usage examples
; -------------------------------------------------------------------------


;A toy function for the examples. It basically does a divide, but
;we cause a 'positive' error if the first argument is not positive
;and we also anticipate that a zero-divide error might occur.
do-average: function [
"calc average from positive total, non-zero count"
total [integer!] count [integer!]] [
print ["In do-average with " total count]
if not positive? total [
cause-error 'math 'positive []
]
total / count ;might cause an error
]

print "No errors here:"
print do-average 10 2
print ""

;the following line (commented out now) displayed:
; *** Math Error: positive number required
; *** Where: do
; and then halted.

; print do-average -10 2 ;I am commented-out now


print "Use try and error? - should trigger 'cause-error'"
either error? result: try [do-average -10 2] [
print ["Error id: " result/id]
] [
print ["No errors, result is: " result]
]

print "Use try and error? - force a zero-divide"
either error? result: try [do-average 10 0] [
print ["Error id: " result/id]
] [
print ["No errors, result is: " result]
]

print "Use try and error? - no errors expected "
either error? result: try [do-average 10 2] [
print ["Error id: " result/id]
] [
print ["No errors, result is: " result]
]
print "Done."

THE OUTPUT IS:
--------------

No errors here:
In do-average with 10 2
5

Use try and error? - should trigger 'cause-error'
In do-average with -10 2
Error id: positive
Use try and error? - force a zero-divide
In do-average with 10 0
Error id: zero-divide
Use try and error? - no errors expected
In do-average with 10 2
No errors, result is: 5
Done.



; -------------------------------------------------------------------------
; /all refinement examples
; -------------------------------------------------------------------------

; make a 'break' error. Try does not detect it.
red>> error? try [print 3 + 4 break "done"]
7
*** Throw Error: no loop to break
*** Where: break

; now use /all to detect it (as well as any other errors)
red>> error? try/all [print 3 + 4 break "done"]
7
== true

top alphanumeric-index category-index



tuple!          type:  datatype!--    Cats: Colors, Datatypes
The  datatype! tuple! is a list of 3 up to 12 bytes. 
It offers a versatile way to represent different kind of values such as
version numbers, IP addresses , and colours (example: 0.255.0).

The value of each item in a tuple must be in the range 0 to 255.

Once a tuple! value is created, its size cannot be changed anymore (it is
not a series!),
but its elements can still be modified, using, for example, path syntax.

The following actions are supported by tuple! values:
random, add, divide, multiply, remainder, subtract,
and, or, xor, length?, pick, poke, reverse.

Math operations are allowed with some other scalar datatypes where a result is sensible,
like integer!, float! and percent!.

Tuples can be used to represent RGB colors. To get a list of the predefined
colors, type:
help tuple!

Examples
; -------------------------------------------------------------------------
; Create 2 tuples
; -------------------------------------------------------------------------

red>> t1: 6.3.2
== 6.3.2

red>> t2: 100.200.64.32
== 100.200.64.32

; -------------------------------------------------------------------------
; Path syntax to access and modify an element
; -------------------------------------------------------------------------

red>> t2/2
== 200

red>> t2/2: 250
== 250

red>> t2
== 100.250.64.32

; -------------------------------------------------------------------------
; Add the tuples
; -------------------------------------------------------------------------

red>> t1 + t2
== 106.253.66.32

; -------------------------------------------------------------------------
; Add an integer - note clipping at 255
; -------------------------------------------------------------------------

red>> t2 + 200
== 255.255.255.232

; -------------------------------------------------------------------------
; Get help on defined colours
; -------------------------------------------------------------------------

red>> help tuple!
aqua : 40.100.130
beige : 255.228.196
black : 0.0.0
blue : 0.0.255
brick : 178.34.34
... and 100 or so lines more, not shown here

; -------------------------------------------------------------------------
; Compare pre-defined colours
; -------------------------------------------------------------------------

red>> red + green = yellow
== true

top alphanumeric-index category-index



tuple?          type:  function!--    Cats: Type Checking
The word tuple? returns true if its argument is a tuple!, 
otherwise false.

Its argument can be of any type.
Examples
; -------------------------------------------------------------------------
; Test a valid tuple!
; -------------------------------------------------------------------------

red>> t: 22.44.33
22.44.33

red>> tuple? t
true

; -------------------------------------------------------------------------
; Test an integer
; -------------------------------------------------------------------------

red>> n: 123
123

red>> tuple? n
false

top alphanumeric-index category-index



type?          type:  native!--    Cats: Type Checking
The word type? returns the datatype! of a value.

The argument can be of any type.

Refinements
/word - returns a word value, rather than a datatype value.
Examples
; -------------------------------------------------------------------------
; Get the type of several items
; -------------------------------------------------------------------------

red>> type? 123
== integer!

red>> type? [1 2 3]
== block!

red>> x: 22x33
== 22x33

red>> type? x
== pair!

top alphanumeric-index category-index



typeset!          type:  datatype!--    Cats: Datatypes
The datatype! typeset! lets us create a set of types and name them.  

Internally, a typeset is stored in a compact array of bits, for fast access
at run-time. By convention, typeset! names should end with a !

The following words are supported with typeset!s:
make
form
mold
and
or
xor
complement
clear
find
insert
append
length?.

Comparison operators are also supported.

Typesets cannot be built from existing typesets; use the low-level types instead.
Examples
; -------------------------------------------------------------------------
; Red uses typeset!s internally:
; -------------------------------------------------------------------------

red>> ? typeset!
any-block! : make typeset! [block! paren! path! lit-path! set-path!
get-path! hash!]
any-function! : make typeset! [native! action! op! function! routine!]
any-list! : make typeset! [block! paren! hash!]
any-object! : make typeset! [object! error!]
any-path! : make typeset! [path! lit-path! set-path! get-path!]
any-string! : make typeset! [string! file! url!]
any-type! : make typeset! [datatype! unset! none! logic! block!
paren! string! file! url! char! integer!
float! word! set-word! lit-word! get-word!
refinement! issue! native! action! op!
function! path! lit-path! set-path!
get-path! routine! bitset! object! typeset!
error! vector! hash! pair! percent! tuple!
map! binary! time! image! event!]
any-word! : make typeset! [word! set-word! lit-word! get-word!
refinement! issue!]
default! : make typeset! [datatype! none! logic! block! paren!
string! file! url! char! integer! float!
word! set-word! lit-word! get-word!
refinement! issue! native! action! op!
function! path! lit-path! set-path!
get-path! routine! bitset! object!
typeset! error! vector! hash! pair!
percent! tuple! map! binary! time! image!]
immediate! : make typeset! [datatype! none! logic! char! integer!
float! word! set-word! lit-word!
get-word! refinement! issue! typeset!
pair! percent! tuple! time!]
internal! : make typeset! [unset! event!]
my-type! : make typeset! [integer! pair! tuple!]
number! : make typeset! [integer! float! percent!]
scalar! : make typeset! [char! integer! float! pair! percent! tuple! time!]
series! : make typeset! [block! paren! string! file! url! path! lit-path!
set-path! get-path! vector! hash! binary! image!]

; -------------------------------------------------------------------------
; Make a new type
; -------------------------------------------------------------------------

red>> my-type!: make typeset! [pair! tuple! integer!]
== make typeset! [integer! pair! tuple!]

; -------------------------------------------------------------------------
; Create a function which uses the type
; -------------------------------------------------------------------------

red>> show-it: function [x [my-type!] ] [ print x ]

; -------------------------------------------------------------------------
; Try it with pair, tuple, integer
; -------------------------------------------------------------------------

red>> show-it 30x40 ; pair! is part of this typeset!
30x40

red>> show-it 33.44.2 ; tuple! is part of this typeset!
33.44.2

red>> show-it 234 ; integer! is part of this typeset!
234

red>> show-it 23.45 ; float! is NOT part of this typeset!
*** Script error: show-it does not allow float! for its x argument
*** Where: show-it

; -------------------------------------------------------------------------
; Try to make a typeset from the existing typeset! number!
; -------------------------------------------------------------------------

red>> t!: make typeset![number!]
*** Script error: invalid argument: number!
*** Where: make
red>>


top alphanumeric-index category-index



typeset?          type:  function!--    Cats: Type Checking
The word typeset? returns true if its argument is a typeset!, 
otherwise false.

The argument can be of any type
Examples
; -------------------------------------------------------------------------
; integer! is a type, not a typeset!
; -------------------------------------------------------------------------

red>> typeset? integer!
== false

; -------------------------------------------------------------------------
; number! is a typeset!
; -------------------------------------------------------------------------

red>> typeset? number!
== true

red>> ? number!
number! is a typeset! of value: make typeset! [integer! float! percent!]

; -------------------------------------------------------------------------
; Test a self made typeset!
; -------------------------------------------------------------------------

red>> my-type!: make typeset! [pair! tuple! integer!]
== make typeset! [integer! pair! tuple!]

red>> typeset? my-type!
== true

top alphanumeric-index category-index



union          type:  native!--    Cats: Series, Sets
The word union returns the union of 2 data sets.  
Duplicate entries are only included once.

A new series! is produced, and the 2 arguments are unchanged.

Both series arguments must be of the same datatype, which can be:
block! hash! string! bitset! typeset!

The word union is one of several set-type functions.

Refinements:
/case - use case-sensitive comparison
/skip - treat the series as fixed size records.
Specify the size as an integer!
Examples
; -------------------------------------------------------------------------
; Union of 2 blocks
; -------------------------------------------------------------------------

red>> union [1 2 99 4] [1 2 3 4]
== [1 2 99 4 3]

; -------------------------------------------------------------------------
; Union of 2 strings
; -------------------------------------------------------------------------

red>> union "abcd" "Ab"
== "abcd"

; /case makes union case-sensitive
red>> union/case "abcd" "Ab"
== "abcdA"

red>> union/case ["a" "b"] [ "A"]
== ["a" "b" "A"]

top alphanumeric-index category-index



unique          type:  native!--    Cats: Series, Sets
The word unique takes a series! as its argument and removes 
all duplicates.

Refinements:
/skip - groups of items are made unique
Examples
; -------------------------------------------------------------------------
; Leave only the unique values
; -------------------------------------------------------------------------

red>> unique [1 2 3 4 2 5 4 1 3 2]
== [1 2 3 4 5]

; -------------------------------------------------------------------------
; Make groups of 2 items unique
; -------------------------------------------------------------------------

red>> unique/skip [1 2 3 4 1 2 3 4 5 6 7 8 5 6] 2
== [1 2 3 4 5 6 7 8]

; -------------------------------------------------------------------------
; Unique characters in a string!
; -------------------------------------------------------------------------

red>> unique "abcbcdcdedefefg"
== "abcdefg"

; -------------------------------------------------------------------------
; Unique groups of 3 characters
; -------------------------------------------------------------------------

red>> unique/skip "abcdefabcghijklmnoghi" 3
== "abcdefghijklmno"

top alphanumeric-index category-index



unless          type:  native!--    Cats: Conditional branching
The word unless evaluates the block! if the condition is NOT true,
returning the value of the block; otherwise returns none.

The arguments are a condition, and a block!.

Using unless is equivalent to using if not.
Examples
age: 18
unless (age < 18) or (age > 100) [print "Within Range"]
Within range

if not( (age < 18) or (age > 100)) [print "Within Range"]
Within range
; equivalent if (for previous unless example)

if (age >= 18) and (age <= 100) [print "Within Range"]
Within range
; same with condition rewritten

top alphanumeric-index category-index



unset          type:  native!--    Cats: Word Manipulation
Unsets the value of a word in its current context. 

Its single argument can be a word! or block! of words.

(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



unset!          type:  datatype!--    Cats: Datatypes, Word Manipulation
This type comes into existence when value slots in memory just contain random 
garbage. It is possible to use it when specifying function argument types,
but doing so reduces Red's error detection.

There are no examples currently.



top alphanumeric-index category-index



unset?          type:  function!--    Cats: Word Manipulation
Returns true if its argument is of the unset! type, otherwise false.  
The value? word is also useful in this area.

Its single argument can be of any type.

Examples
; -------------------------------------------------------------------------
; unset? and value?
; -------------------------------------------------------------------------

; print does not return a value
red>> unset? print 22
22
== true

; value? does not work with unset!
red>> value? print 22
22
*** Script Error: value? does not allow unset! for its value argument
*** Where: value?

top alphanumeric-index category-index



until          type:  native!--    Cats: Iteration
The word until evaluates its block! argument until the block!
returns a true value.

It has one argument, a block!.
Examples
n: 5
until [
print n
n: n - 1
n < 0
]
5
4
3
2
1
0
== true

top alphanumeric-index category-index



uppercase          type:  native!--    Cats: String manipulation
The word uppercase converts a string of characters to upper-case. 

The single argument can be a string! or a char!.

Refinements:
/part - limits to a given length or position.

NOTE: this is a destructive operation.
When applying it to a variable, that variable will be changed!

See also lowercase.
Examples
; -------------------------------------------------------------------------
; Try uppercase on char and string
; -------------------------------------------------------------------------

red>> uppercase #"a"
#"A"

red>> uppercase "ABC def"
"ABC DEF"

; -------------------------------------------------------------------------
; Use /part to specify first 2 chars only
; -------------------------------------------------------------------------

red>> uppercase/part "abcd def" 2
ABcd def"

top alphanumeric-index category-index



url!          type:  datatype!--    Cats: Datatypes, URL/Internet
The datatype! url! (Uniform Resource Locator) lets us 
access web pages, images, files, ftp, email, and other protocols.

It is a series! similar to a string, and values take the pattern:
protocol://path
For example:
http://www.red-lang.org/p/about.html

A url! can be used with a variety of words, such as do, load,
read, write and save.
Examples
; -------------------------------------------------------------------------
; Create a URL, read the file
; -------------------------------------------------------------------------

red>> web-file: http://www.red-lang.org/p/about.html
== http://www.red-lang.org/p/about.html

red>> type? web-file
== url!

red>> read web-file
; Output suppressed

red>> print read web-file
; Output suppressed

top alphanumeric-index category-index



url?          type:  function!--    Cats: Type Checking, URL/Internet
Returns true if its argument is a url! type, otherwise false.
It does not do a complete check of the URL for current protocols.

Arguments
Its single argument can be of any type.

Examples
; -------------------------------------------------------------------------
; Try url? on various types
; -------------------------------------------------------------------------

;string type, not a url
red>> url? "http://www.google.com/"
== false

;a url
red>> url? http://www.google.com/
== true

;a non-existent protocol, still a url
red>> url? xxx://a.b.c
== true

top alphanumeric-index category-index



value?          type:  native!--    Cats: Type Checking
The word value? returns true if the argument is a Red word!
that has been set; otherwise returns false.

It has 1 argument, a word!, which is passed as a literal
or as the result of other operations.
Examples
a: 33
== 33

value? 'a
== true

a: none
== none

value? 'a
== true

value? 'fish
== false

value? second [a fish]
== false

value? fish
*** Script error: fish has no value
*** Where: value?
; NOTE the error message;
; we must prevent evaluation of the word by using ' or [ ].

top alphanumeric-index category-index



values-of          type:  function!--    Cats: Reflection
Returns the list of values of a value that supports reflection. 

Arguments

A value of a type that supports reflection.

Examples
; -------------------------------------------------------------------------
; values-of, with map and object
; -------------------------------------------------------------------------

;with a map
red>> m: make map![a 1 b 2]
== #(
a: 1
b: 2
)
red>> values-of m
== [1 2]

;with an object
red>> place: make object! [ x-pos: 100 y-pos: 200 ]
red>> values-of place
== [100 200]

top alphanumeric-index category-index



vector!          type:  datatype!--    Cats: Datatypes
The datatype! vector! represents a series! type.

A vector! is a high-performance series! of items.
The items in a vector! must all have the same type (unlike a block!).

The allowable item types are:
integer! float! char! percent!
Vectors of string! are not allowed.

To create a vector, we use make, as in:
v-ages: make vector! [80 18 65]

At least one value must be given, to allow to determine the type.
Examples
; -------------------------------------------------------------------------
; First create a vector! of integer!
; -------------------------------------------------------------------------

red>> v-ages: make vector! [80 18 65]
== make vector! [80 18 65]

red>> print v-ages
80 18 65

red>> print mold v-ages
make vector! [80 18 65]

; -------------------------------------------------------------------------
; Add a new item to that vector!
; -------------------------------------------------------------------------

red>> append v-ages 99
== make vector! [80 18 65 99]

red>> print v-ages
80 18 65 99

; -------------------------------------------------------------------------
; Obtain the length of it
; -------------------------------------------------------------------------

red>> print length? v-ages
4

; -------------------------------------------------------------------------
; Extract an item using path notation
; -------------------------------------------------------------------------

red>> print v-ages/2
18

; -------------------------------------------------------------------------
; Return sub series! starting with found item
; -------------------------------------------------------------------------

red>> find v-ages 18
== make vector! [18 65 99]

; -------------------------------------------------------------------------
; Loop through a vector!
; -------------------------------------------------------------------------

red>> grades: make vector![ #"A" #"B" #"F"]
== make vector! [#"A" #"B" #"F"]

red>> foreach grade grades [print grade]
A
B
F

top alphanumeric-index category-index



vector?          type:  function!--    Cats: Type Checking
The word vector? returns true if its argument is a vector!, otherwise false.

Its single argument can be of any type.
Examples
; -------------------------------------------------------------------------
; Create a vector! and a block!, then explore vector?
; -------------------------------------------------------------------------

red>> v-ages: make vector! [80 18 65]
== make vector! [80 18 65]

red>> vector? v-ages
== true

red>> a-block: [ 80 18 85]
== [80 18 85]

red>> vector? a-block
== false

top alphanumeric-index category-index



wait          type:  native!--    Cats: System Related
Waits for a duration in seconds. or specified time!. It can also wait for ports.  

Arguments

The single argument can be a number!, block!, time!, none!.

Refinements

/all - Returns all events in a block.

Examples
; -------------------------------------------------------------------------
; simple wait for 20 seconds
; -------------------------------------------------------------------------

red>> now/time
== 13:34:56
red>> wait 20 ;wait happens here
== none
red>> now/time
== 13:35:21

top alphanumeric-index category-index



what          type:  function!--    Cats: Documentation, Help & Debug
The word what displays brief information about every Red function,
one per line.

Has no arguments or refinements.
Examples
red>> what
to : Converts to a specified datatype
not : Returns the negation (logical complement) of a value
remove : Returns the series at the same index after removing a value
while : Evaluates body as long as condition is true
any : Evaluates, returning at the first that is true
copy : Returns a copy of a non-scalar value
insert : Inserts value(s) at series index; returns series head
if : If condition is true, evaluate block; else return NONE
... a lot more lines are displayed ... omitted here

top alphanumeric-index category-index



what-dir          type:  function!--    Cats: Files
The word what-dir returns the active directory path as a file! value.

It has no arguments.

Irrespective of the operating system, it uses / in file paths.

Literal file paths must start with the % sign:
So, e.g. c:\windows\system32 must be represented as %/c/windows/system32
Examples
a: what-dir
== %/C/rebol/

type? a
== file!

top alphanumeric-index category-index



while          type:  native!--    Cats: Iteration
The word while has two arguments:
- a condition block!
- a body block!

As long as the condition block! returns true, the body block!
will be evaluated.

NOTE that in Red, a block! can contain several evaluations; only the value
resulting from the final evaluation influences the while condition.

The word break can be used to break out of the body block!.

In the case where several conditions control the loop continuation, you might
require short-circuit evaluation of the condition using all.

When working with series!, you should investigate existing functions like
first, rather than writing complex loops.
Examples
count: 1
while [count <= 5] [
print count
count: count + 1
]
print "Done"
print count
1
2
3
4
5
Done
== 6

while [all [ n < 10 still-ok] ] [
body ; which might alter n and/or still-ok
]
; Either condition going false will terminate the loop.
; The extra [ ] are because the condition must be inside a block.

top alphanumeric-index category-index



within?          type:  function!--    Cats: Math
Return true if the point is within the rectangle bounds, otherwise false.

Arguments
point - a pair! - XY position of point. Origin is at upper left corner.
offset -a pair! - Offset of area, i.e. upper left corner of a rectangle.
size - a pair! - Size of area, i.e. width, height of area.


Examples
; -------------------------------------------------------------------------
; Explore possibilities for within?, with 8x2 area, corner at 5x10
; -------------------------------------------------------------------------

;5x5 outside
red>> within? 5x5 5x10 8x2
== false

;12x11 inside
red>> within? 12x11 5x10 8x2
== true

;5x10 on edge, considered inside
red>> within? 5x10 5x10 8x2
== true

top alphanumeric-index category-index



word!          type:  datatype!--    Cats: Datatypes
A word! type is a symbolic value that can be used like a variable, an 
identifier that refers to a value in a given context.

See word?"

top alphanumeric-index category-index



word?          type:  function!--    Cats: Type Checking
The word word? returns true if its argument is a word! type, 
otherwise false.

Its single argument can be of any type.
Examples
; -------------------------------------------------------------------------
; Try word? with various types
; -------------------------------------------------------------------------

red>> word? "abc"
== false

red>> word? 123
== false

red>> word? abc
*** Script Error: abc has no value
*** Where: word?

'a word
red>> word? 'abc
== true

red>> word? first [abc]
== true

red>> x: 3
== 3

red>> word? x
== false

red>> word? :x
== false

red>> word? first [x]
== true

top alphanumeric-index category-index



words-of          type:  function!--    Cats: Reflection
Returns the list of words of a value that supports reflection. 

Arguments

A value of a type that supports reflection.

Examples
; -------------------------------------------------------------------------
; words-of, with map and object
; -------------------------------------------------------------------------

;with map
red>> m: make map![a 1 b 2]

red>> words-of m
== [a b]

;with object
red>> place: make object! [x-pos: 100 y-pos: 200 ]

red>> words-of place
== [x-pos y-pos]

top alphanumeric-index category-index



write          type:  action!--    Cats: Directories, Files, Output
Writes data to a file!, url!, or other port.

Arguments
1. destination: a file! or url!
2. data to write: any type.

Refinements
/binary - preserves contents exactly. Use for images, etc.
/lines - write each value in a block as a separate line.
/info - no details available currently
/append - write data at end of file.
/part - partial write a given number of units.
We provide a length, as a number!.
/seek - write at a specific position. We provide a position,
as a number!.
/allow - specifies protection attributes. We provide access
details in a block!.
/as - write with the specified encoding, default is 'UTF-8.
We provide the encoding as a word!.


Examples
; -------------------------------------------------------------------------
; Use write. Note the preceding % for literal file names.
; -------------------------------------------------------------------------


;write 1 line to local file testfile.txt
red>> write %testfile.txt "ABCDEFG"
;read it back
red>> read %testfile.txt
== "ABCDEFG"
;/seek refinement
red>> write/seek %testfile.txt "XXX" 2
;read it back
red>> read %testfile.txt
== "ABXXXFG"

; /lines refinement
red>> write/lines %testfile.txt ["a line" "another line"]
;read it back, use print to avoid console formatting
red>> print read %testfile.txt
a line
another line


top alphanumeric-index category-index



write-clipboard          type:  routine!--    Cats: Output, System Related
USAGE:
WRITE-CLIPBOARD data

DESCRIPTION:
Write content to the system clipboard.
WRITE-CLIPBOARD is a routine! value.

ARGUMENTS:
data [string!]
; -------------------------------------------------------------------------
; write-clipboard
; -------------------------------------------------------------------------

>> write-clipboard "Hello!!"
== true
>> read-clipboard
== "Hello!!"

top alphanumeric-index category-index



write-stdout          type:  routine!--    Cats: Output, System Related
USAGE:
WRITE-STDOUT str

DESCRIPTION:
Write data to STDOUT.
WRITE-STDOUT is a routine! value.

ARGUMENTS:
str [string!]
(Awaiting additional documentation by red-by-example team.)

top alphanumeric-index category-index



xor          type:  op!--    Cats: Bit manipulation
The word xor returns the exclusive "or" of its two arguments.

The type of both arguments can be:
logic! integer! char! bitset! typeset! pair! tuple! vector!

xor provides a sensible interpretation of "true when different"
for types and combinations of types.

The result type is determined by the type of the first argument.

Certain combinations of types are disallowed.
Examples
3 xor 2
== 1

3x3 xor 2x2 ;pairs
== 1x1

3x0 xor 3x1
== 0x1

#"A" xor 2 ;character, number
== #"C"

2 xor #"A"
== 67

#"A" xor 2
== #"C"

true xor false
== true

true xor true
== false

3 xor 2x1
*** Script error: xor does not allow pair for its value2 argument
*** Where: xor

123 xor true
*** Script error: logic type is not allowed here
*** Where: xor

top alphanumeric-index category-index



xor~          type:  action!--    Cats: Bit manipulation
Returns the  exclusive OR of its 2 arguments.

It is the functional equivalent of the xor infix operator.

Examples
; -------------------------------------------------------------------------
; Explore some types
; -------------------------------------------------------------------------

red>> xor~ 3 3
== 0
red>> xor~ 1 3
== 2

red>> xor~ #"A" 1
== #"@"
red>> xor~ #"D" 1
== #"E"


top alphanumeric-index category-index



yes          type:  logic!--    Cats: Boolean, Constants
The value yes can be used as the boolean value true.
Examples
red>> yes
== true

red>> not yes
== false

top alphanumeric-index category-index



zero?          type:  native!--    Cats: Comparison
The word zero? returns true if its argument is zero; 
otherwise false.

Has one argument: a number! or a pair!.
Examples
zero? 3
== false

zero? 3.1
== false

zero? 0
== true

zero? 2x0
== false

zero? 0x0
== true

top alphanumeric-index category-index