AltME groups: search

Added REMOVE action, supports any-series! and none! datatypes.

As is "Red" name:

http://en.wikipedia.org/wiki/Red_(Taylor_Swift_album)
http://www.sfr.fr/telephonie-mobile/series-red-de-sfr.html
and many more...

stack/arguments will return you a pointer on a series slot in stack. 
If you want to access it's data value, you need:

    int: as red-integer! stack/arguments
    print int/value

Modifying is straightforward:
    int/value: int/value + 1		;-- incrementing example.


Last return value should be at stack/arguments position, in this 
case, it is already.

INSERT action implemented for all series datatype. Unit tests are 
welcome.

It's too early to stress test the memory manager, as it's not yet 
completed for the handling of bigger series.

My small test was for a FILTER function:

filter: function [
	"Returns all values in a series that match a test."
	series [series!]

 test [function!] "Test (predicate) to perform on each value; must 
 take one arg" ; TBD: any-function!
	/out "Reverse the test, filtering out matching results"
][
    result: copy []
    ; The lambda here is like QUOTE, but it evaluates.
    op: either out [:not] [func [val] [:val]]
	foreach value series [
		if op test :value [append/only result :value]
	]
	result
]

; JS-like MAP. The order of args to the function is a bit odd, but 
is set

; up that way because we always want at least the value (if your 
func takes

; only one arg), the next most useful arg is the index, as you may 
display

; progress, and the series is there to give you complete control 
and match

; how JS does it. Now, should the series value be passed as the head 
of the
; series, or the current index, using AT?
map-js: func [

 "Evaluates a function for each value(s) in a series and returns the 
 results."
	series [series!]

 fn [function!] "Function to perform on each value; called with value, 
 index, and series args"
	/only "Insert block types as single values"
	/skip "Treat the series as fixed size records"
		size [integer!]
][
	collect [

  repeat i length? series [   ; use FORSKIP if we want to support /SKIP.
			keep/only fn series/:i :i :series ; :size ?
		]
	]
]
;res: map-js [1 2 3 a b c #d #e #f] :form
;res: map-js [1 2 3 a b c #d #e #f] func [v i] [reduce [i v]]
;res: map-js [1 2 3 a b c #d #e #f] func [v i s] [reduce [i v s]]
;res: map-js "Hello World!" func [v i s] [pick s i]

Yes, in compiler.r, I did replace SELECT on most places where it 
was used on hash! series.

Looks like the newer Beagleboards are using regular ARM CPU (no more 
Cortex-M series), so Red should run just fine on them:

http://techcrunch.com/2013/04/23/the-beaglebone-black-is-a-new-single-board-computer-that-can-brew-beer/

rejoin: func [

 "Returns a new string (or same series type as block/1) made from 
 reduced values."
	block [block!]
	/local op
][
	either empty? block: reduce block [block] [
		op: either series? first block [:copy] [:form]
		append op first block next block
	]
]

My first impressions on your proposition:


1) arr[i] is a useless syntactic addition as we already have indexed 
accesses: arr/i


2) #7 and #8 are going way too far from the Red/System application 
domain, it's basically  a series abstraction. Red internal API already 
provides series (the internal API is not yet completed nor formalized 
though), so this is both unneeded and overlapping with Red standard 
library.


What you might not realize is that you already have array-like capabilities 
with Red/System pointers (including structs and c-strings). If you 
want automatic memory management in Red/System, you won't have it, 
low-level programming requires a manual management of memory for 
accuracy and avoiding unnecessary burdens.


The only array-like part that Red/System is really missing right 
now is the literal array-like declarations, which can be achieved 
without a new formal array! type. As I said earlier, adding a array! 
type would only add bound-checking abilities (which is a nice feature 
to have) and provide you with #5 as a side-effect (not very useful 
anyway, as array would be fixed-size).

Is there garbage collection/reuse of series slots? Not series content, 
but their slots in the series pool?

Yes, they use a stack-based allocation system, so each time a slot 
is popped, it becomes available for a new series. But, as series 
are not freed yet, slots are not popped.

Remember that a c-string! is a pointer to a memory address. Much 
like a string! in REBOL is a reference to the storage of a series 
value that can be referenced by multiple string!s, each with their 
own index

I know list of enhancements for R/S 2.0 exists, yet I don't expect 
it having more advanced series handling ...

I canunderstand, but where exactly would you drive the line? We start 
with series, next we ask for IO, then we request parse :-)

Another thing is that the classic SDL that's available everywhere, 
currently the 1.2.x series, is single-window. To get a proper R3 
host with multiple windows you need SDL 1.3, which is usable but 
is in a very stretched out development process, like R3. 1.3 has 
Android and iOS support, so you'd usually want that, anyway, but 
it's harder to get ready to download binaries for it, and I haven't 
tested it with my binding yet

It would make sense for maps, where SELECT and PICK are pretty much 
the same thing, but not for series, where they mean something different.

PICK for series just means the index, or something that can be translated 
into an index like logic is.

CFOR, EVERY etc

I'm happy with FOR as I do not need to construct and perhaps REDUCE 
a block to set up variable start conditions -- just have to set words 
to values.

For me, the syntaxtic sugar neatness of the new proposals is outweighed 
by the simplicity of the setup for the existing method.


No real opinion on how to standardise the existing behavior other 
than to reiterate a point Brian has already made: FOR start and end 
can work on series too; all the examples I've seen of proposed change 
behavior is for numbers. We need to ensure thar series FORing works 
as expected too.

Nice work, Gregg - thanks for doing all that.


I am having trouble getting LOOP to do what  FOR can do with a series:
    ser: [1 2 3 4 5 6 7]
    for v ser skip ser 5 2 [print v]
        1 2 3 4 5 6 7
        3 4 5 6 7
        5 6 7

Neither of these work for me:
    loop [v ser skip ser 6 2] [print v]
    loop compose [v ser (skip ser 6) 2] [print v]

Good catch. I just added series support, and since it's a simple 
dialect, it won't like that. In the current version, you would have 
to use an interim var for 'end. e.g.:

>> b: (skip ser 6)
== [7]
>> loop compose [v ser b 2] [print v]

Thanks Gregg.

If FORing on a series is relatively uncommon, then (per curecode 
#666) losing the direct ability would be a good R3ish thing to do.


I am little more concerned about LOOP set up needing COMPOSE in a 
way that existing looping constructs do not. The cost of creating 
simplicity in the language core should not be exporting complexity 
to the language users.

Benefits to the local binding:

- You define new words that go away when the function ends, *if you 
want them to*

- The context created is an object context, which makes word lookup 
faster (O(1) instead of O(n))

- The context created can be references safely after the function 
ends

- All series in the loop body are copied, which makes them safe to 
modify during and after the loop, making binding loops even more 
task and recursion safe than non-binding loops.

Sunanda, agreed on not export complexity. Words are supported directly, 
and we can look at making everything easy that it should support. 
Today, words are supported. e.g.:

a: 1
b: 5
loop [i a b 1] [print i]


Series values, as in your first bug report, are the thing I have 
to look into. Beyond that, should it just evaluate everything it 
gets?


Marco, FOR-STEP sounds too close to FORSKIP to me. Have to think 
about how FORSKIP fits in to the model. For that, and IN-RANGE, the 
main question is what their purpose is. On your first CFOR tests, 
I get these results:

>> probe cfor [num: 1] [num <= 3] [num: num + 1] [print num "a"]
1
2
3
4
== 4

>> probe cfor [num: 1] [num <= 3] [num: num + 1] [if num = 2 [throw 
make error! "what 2?"] "a"]
** Throw Error: ** User Error: what 2?
** Near: throw make error! "what 2?"

SHA2_Series could switch on width (224, 256, ... -- perhaps defined 
in an enum) rather than a symbol, but this made the logic in N_checksum 
cleaner.

Let's widen the discussion a bit. Spitting a string at a delimiter. 
Easy enough to define clear behavior if the series contains the delimiter, 
but what if it doesn't? Most split funcs return an array, splitting 
at each dlm. If no dlm, return the original series as the only element 
in that array. 


What if we always want to return two elements? e.g., we have a SPLIT-AT 
func that can split a series into two parts, given either an integer 
index or value to match. Let's also give it a /LAST refinement, so 
it can split at the last matching value found, like FIND/LAST works. 


Given that, what do you expect in the case where the dlm (e.g. "=") 
is not in the series?

    SPLIT-AT "abcdef" "="   == [? ?]
    SPLIT-AT/LAST "abcdef" "="    == [? ?]

Max said: "split-path shoudn't invent information which isn't given 
to it"


I agree, if we consider split-path to be operating in string mode 
(the rejoin invariant). If we want to have a file-system aware option, 
what would we call the refinement? Or should it be a separate function?


As far as returning none for either part, it strikes me as inconsistent 
(if convenient, which it may be). That is, if you split a series 
into two parts, splitting at the head or tail should just give you 
an empty series for that part, shouldn't it? This comes back to my 
SPLIT-AT question.

However, fortunately, the ARGS series is unique to function (since 
it is created specifically for the function), so it can be used instead 
of the body.

Only series and GOBs need GC

Ah, so they can only be contained within a series.

Continuing from #Red group. A johnk asked for multi-line source from 
Carl. This is my W_GETS code in World, which has multi-line (blocks 
and long strings). I don't know, if you can use it, as World might 
be different internal:

char prompt_str[]	= "prin system/console/prompt";
char block_str[]	= "prin system/console/block";
char string_str[]	= "prin system/console/string";

#define W_GETS \
	if (W->line_read) { \
		free (W->line_read); \
		W->line_read = NULL; \
	} \
	if (W->top_of_series > W->series_base) { \
		W->stack = W->stack + 1; \
		int trace = W->trace; \
		W->trace = 0; \
		if (*W->top_of_series == BLOCK_BEGIN_T) { \
			tv.newline = 1; \
			do_string (W, block_str); \
			int i; \
			for (i = 0; i < W->top_of_blocks - W->blocks; i++) \
				w_printf ("    "); \
		} else { \
			do_string (W, string_str); \
			w_printf ("    "); \
		} \
		W->trace = trace; \
		W->stack = W->stack - 1; \
	} else { \
		W->top_of_code = W->code - 1; \
		W->top = -1; \
		if (NULL != W->P) \
			printf ("**** W->P != NULL ****\n"); \
		W->stack = W->stack + 1; \
		int trace = W->trace; \
		W->trace = 0; \
		do_string (W, prompt_str); \
		W->trace = trace; \
		W->stack = W->stack - 1; \
	} \
	W->line_read = w_readline (&auto_brackets, &tab_completion); \
	reset_stack (W); \
	if (W->line_read == NULL) throw_error (W, ERRMEM_S); \
	if (W->line_read[0] == KEY_CTRL_D) throw_error (W, QUIT_S); \
	W->save_line_read = W->line_read;

Some exmplanation:


W->top_of_series is a stack holding the different types of series 
being entered in the lexer, defined as:

#define BLOCK_BEGIN_T		58
#define PAREN_BEGIN_T		59
#define LONG_STRING_BEGIN_T	60
#define PATH_BEGIN_T		61
#define GET_PATH_BEGIN_T	62
#define LIT_PATH_BEGIN_T	63
#define BINARY_BEGIN_T		64
#define SET_GET_PATH_T		65


The code about trace is just, if tracing is on or off in World. W->top_of_code 
is a pointer to where the code for the virtual machine in World is 
being created, and W->code is the bottom of that stack in instructions, 
W->top the top. do_string executes a string of World code.

You could even redefine IN, and get exactly, what's asked for:

>> series: [1 2 3]
== [1 2 3]
>> in: the: func [v] [:v]
>> foreach item in the series [print item]
1
2
3
>>

#[[Bo
Rebol 2.101.0.4.20:

>> difference #{FFFFFF} #{EEEEEE}
== #{FFEE}

I would expect it to return #{111111}
]]Bo

That is not a well informed expectation, Bo.:


* in Rebol, binary values are series of octets (small integers, 0 
to 255)
* in Rebol, set functions handle series as sets of values
* DIFFERENCE is a set function yielding set difference

* in the above case the first st contains #{FF} (=255), which is 
not contained in the second series

* the second series contains #{EE} (=238), which is not contained 
in the first series
* thus, the set difference is #{FFEE}

Bo, I'm not sure, if that makes sense. What you're suggesting is, 
that this should be possible:

	(read/binary %file1) - (read/binary %file2)


So it's like looking at a long sequence of binary data as a number? 
And if the series are of different length, they should be right aligned. 
Is that really useful? :)

Arithmetic on series ... like arithmetic on strings!? Funny language, 
that do things like that.

I get the same as PhilB: "**Crash : expand series overflow"  rvdraw57e, 
 WinXP

I would like that too. but a path! is a series, maybe that is tricky? 
but we could set the last element to unset.

#3687 : bitwise ops - it was submitted at the start of the /View 
1.3 project (2003/2004). 

Both MacOS 9 and Amiga /View 12.1 (big-endian MC 680xx / PowerPC) 
have this bug for bitwise operations on series.

I had to do a workaround for %gzip.r (painful slow byte per byte 
operations) and %rebzip.r (calculations with integers.)

(split-path mucks up when its target argument is at a series offset.)

If you have ever tried APPENDing a Block to a Block as a Block (ie. 
append ["a"] to [] and have it be [["a"]])  Then you prolly know 
that you have to jump through a couple of hoops to do it.  The same 
goes to append a string to a string.  Now there are a lot of times 
that I need to append one series to another as a "sub-series" it 
seems to me that this should be much simpler to do, maybe a refinement 
to APPEND.  Any thoughts?

Thanks for the strict-greater? idea.  I was hoping there was a built-in 
ability somewhere.

One tiny tweak to the function -- you need to restrict the two values 
to series or you can get strange results:
     >> strict-greater? make object! [1] make object! [0]
     == false
     >> greater? make object! [1] make object! [0]
     ** Script Error: Cannot use greater? on object! value
So:

 strict-greater?: func [value1 [series!] value2 [series!]] [(to-binary 
 value1) > (to-
binary value2)]

Thats what series are about. :) And we can make our own using ports 
:)

about Roberts stack: most of that is inbuild in series, so why wrap/rename 
it?

POP is about the most useful method that isn't built into REBOL. 
It's nice to be able to remove something and have it returned, rather 
than having the series returned.

Looking at 'ALTER.. shouldn't there be a similar word that "If a 
value is not found in a series, append it; otherwise, DO NOTHING?

In other words.. i want to check the series to see if the word exists.. 
if not, add it..

After all a file is just a binary! series

On a related theme......Is there an easy/built-in way to check if 
all values in a series are equal?  I'm using

     all-equal?: func [ser [series!]] [ser = join next ser first ser]
As in:
    all-equal? [1 1 1 ]
    == true
    all-equal? "yyy" 
    true
    all-equal? %xxx
     true

Volker, it should operate on series values as well, like FOR does 
today. My examples are all numbers, because that's easier to do concisely. 
:-)

assume: func [
    {If a value is not in a series, append it.}
    series [series! port!]
    value
][
    any [find series value insert tail series :value]
]

I get the following error when I do this: ** Script Error: foreach 
expected data argument of type: series
** Near: foreach message mailbox [
    print message
    ask "Next? "
]
close

I reversed the series so that you remove them from the end backwards

as otherwise I guess the numbering changes if you remove from the 
head instead

I have that problem all the time with having to write

	first find series val

as:

	if f: find series val [f: first f]

first find series val?

The problem I see is that it complicates debugging.

>> 1 + index? find "abc" "e"

** Script Error: index? expected series argument of type: series 
port
** Near: 1 + index? find "abc"

>> 1 + attempt[index? find "abc" "e"]
** Script Error: Cannot use add on none! value
** Near: 1 + attempt [index? find "abc" "e"]

You guys can also think about, how many different colors are needed 
(preferred), when displaying REBOL source. A color for comments, 
values, datatypes, words, etc. Should values be split into numeric 
values, series and others with each their color. Other things?

Hmm... How to do that?
We need to know where a particular
Maybe:
1. Read script *and* Load script
2. Visit each item in the loaded block, recursively.
3. As each item is visited, check its type.

4. Depending somewhat on type, parse (in the READed script) to the 
molded item:
4.1  If it's a series, search for the "opener", eg. block! -> "["
4.2  If it's a non-series, search for it molded.
4.3

It's possible....But may take a while.

For now, you could publish extension code on REBOL.org as an article 
(or series of articles).

the flag is set by each function that modified the series. It's in 
ctx-text (insert-char, edit-text for the most).

caret position is simply the text position (series position) of the 
text.

Yes -- but you need to append, compose or mold it to make it the 
right series of characters for Layout to understand.

Thanks a lot.  It the kind of thing I normally learn the hard way, 
like the first time I was confronted to [ ] instead of copy [ ]. 
 Judging when it is better to use a block or object or structure, 
hash or else is not evident from a new eye.  The small Ladislav tutorial 
on blocks (series) is the kind of thing that helps a lot,, it help 
a newcommer realise how the language is articulated.

Hello all.. I need help!  I am trying to append a series within a 
series..  i.e.  [ [a b c] [d e f] ].  How would I add [g h i] to 
the end of my series so that I would have [ [abc] [ d e f] [g h i] 
], and not [ [a b c] [d e f] g h i ] ?

Tom: Yes, I was aware of read/lines and how it is similar (apparently 
not the same) as parse/all series "^/".  read/lines worked just fine.

I don't know why last night I wasn't happy with read/lines - must 
have been tired!

yeah, each rule stop at a position, not going past it. that way you 
wouldn't be able to reach the tail of the series. THRU will get you 
to the tale

No printer support yet. We're planning to port and integrate CUPS 
in the 0.6.x series, which we will start soon. Basic printer support 
will probably happen in the coming year

We're now officially out of the 0.5.x series, which were meant to 
update our base technology and were thus fairly chaotic. We now have 
a good development platform for the innovations that we have been 
planning

Does anyone have any ideas about how to approach a web-based gui 
that allows users to upload multiple files at one time without having 
a series of  "inputs?" I'd like to have users do a ctrl select when 
they are browsing for multiple files to send. Thanks.

SAX apis don't work like that. They generate a series of events, 
not a series of data.

you can just do a mold/all load, that will in effect copy the whole 
tree along with all the series too.

Wow...I don't track laptops the same way.  I'm on this right now 
http://store.shopfujitsu.com/fpc/Ecommerce/buildseriesbean.do?series=P7120D
Very small, but I LOVE it!

Ok thanks. I'll double check the exact number tommorrow, but it's 
the 8.1 series. LIMIT would be a good idea, but the query returns 
only one row. It's the amount of data in the one column that is the 
problem. (Whole HTML reports in one chunk). I was thinking that I 
should split up the report into a set of smaller chunks as it gets 
generated  anyway.


I'll give you some more info tommorrow. I appreciate you are busy 
with Cheyenne, so thanks for your time.

I am trying PGSQL with Doc's protocol and getting 'open pgsql'  error 
"** Script Error: find expected series argument of type: series object 
port bitse
t

** Near: fast-query: either args: find port/target"     This is Postgres 
9.0 recently downloaded.   Anyone having success with it?

it is a series .... [this is what?] - now how can you tell what is 
inside? is it code? or literal data? try to execute it with "do" 
- if it fails, it was not code :-)

hmm, you said it is like lisp - so yes, it is so ... I explained 
to my friend, that everything is a series/block (strings in Reichart's 
post). And you have basic set of commands to operate on strings - 
insert, delete, change, append, remove, find, first ... tenth ....... 
and you have 'do to do the code ...

series and its operations everywhere ... that is how I would start 
....

I will recommend you read the PLT book, or the CTM Book. This introduce 
a lot of the concepts present in rebol, and you can get a sense on 
how to programm with series (lists), how to use func are as natural 
as integers, and how to drive your programs around the data structures, 
and not around the memory management.

Yes, if we have a word set to a value like this:
	word: 123
then there is a series of possible "reductions" possible:
	'word  ->  word  ->  123

Likewise for a function:
	word: func [][print "hello"]
The reductions:

 'word  ->  :word (gives unevaluated function)  ->  word (evaluates 
 the function to print "hello")

Don't forget Forth in the heritage list! Lisp/Logo and Forth are 
key design ancestors, for lists/blocks and words, respectively.

So, the main things I think of as far as basic concepts are:


1) Everything is data; sometimes that data is evaluated and things 
happen.


2) Everything lives in blocks; there are series operations that you 
need to understand in order to manipulate them.

3) Everything is data.


4) Words are very important; not only knowing when they are evaluated 
and other technical details, but also how you choose them so they 
work together well.

5) Everything is data.

Peter, series values are really a pointer to the series data and 
an offset. When you assign a series value to a word, that pointer 
and offset are copied into the value slot that is currently associated 
with that word (until it is bound to another context). The actual 
series data pointed to is unchanged, though.

I think that it would be good to have visual drawing - sentences 
as "symbol that is pointed to by  a word" is kind of abstract for 
newbies. And what bothers newbies? When the series is unique and 
not shared. I know cases where I better use 'copy, because I am not 
really sure, what rebol will do ...

ball part figure, I'd say basic I/O and core series handling.

Although the "choose a task first then learn what needs to be used 
to code it" approach is fine in many circomstances, in a 45 hours 
course, the student ends up knowing how to code a few tasks (hopefully 
more than one, but not necessarily), but often has a very hard time 
transferring this knowledge to other tasks.


So I think a better "generalist" approach would be to categorize 
generic tasks, like "file manip"', "math", "iterations", "series", 
"network sharing of data", ... and identifying just a few native 
words category that are enough to solve all or most problems given 
in those categories.

Strings and blocks are both series, so first, next find etc work 
on both, but when you load you get a block and the units are values. 
When you read, you have a string and the units are characters.

also remember that find, does not copy the series, it returns the 
serie at a different index.

The second one got the right part of the series

On "append append", yes. You could also do it like this: "append 
line join blk/:n tab", the difference being that APPEND modifies 
its series argument, and JOIN does not.


REPEAT is 1-based, not zero, Anton is using "-1 + length? blk" rather 
than "(length? blk) - 1" or "subtract length? blk 1". The first of 
those cases requires the paren because "-" is an op! which will be 
evaluated before the length? func, so REBOL would see it like this 
"length? (blk - 1)", which doesn't work.

First question: what 'instructions' are implemented in rebcode ? 
Seems like series are not implemented.

Series traverse seems to work, but I'm not able to pick, poke or 
change something

apply result find [series value]   :-)

How to traverse with series in rebcode? I wanted to make ucs2 encoder 
using rebcode but found out, that I'm not able to traverse the series 
by 2 chars

Series in rebcode are offset-1 based like normal (except image positions 
in DRAW). Would it be a good idea to make them offset-zero based 
in rebcode? Example: if I wanna read a pixel value at a certain position 
in REBOL, I could write:
image/1
or
first skip image position
(If position was 0x0, I'll get the first pixel.)

If I pick an image in rebcode at offset 0, I get an out of range 
error. It's a tough decision, but what seems most 'correct'?

http://video.google.de/videosearch?q=hp+labs+google+techtalks


This are two of a series of four (2 more to come in the next 2 weeks 
(if I remember correctly)) talks about capability security. I think 
they're highly educational, interesting and anyway important to widen 
ones view on security issues we face nowadays. Highly recommended. 
:-) (best to download the Google Video player and watch them by downloading 
them)

I got an error in the 'sql func ...


** Script Error: length? expected series argument of type: series 
port tuple bitset struct
** Where: switch
** Near: *bind-text sid i val length?

the database is opened with /direct refinement.

The call is:
	sql ["select * from person where guid = ?" guid1]


Where I know, that the dataset with this guid exists, because I have 
just got it from another selsct.
The dataset contains only strings, some of them empty.


Well, this is it: ["h-o-h.org_20060326_182311691_1224" "Urte" "Hermann" 
"Urmeli" "" "" "" "" "" "" "" "" "" "" "Opera ID: 359" "" "" ""]

And I am using the right guid.

Any ideas?

So, the error in one small message: 

>> sql ["select * from person where guid = ?" #"a"]

** Script Error: length? expected series argument of type: series 
port tuple bitset struct
** Where: switch
** Near: *bind-text sid i val length?

From his blogs it appears that Carl is just extracting SQLite's btree 
and indexing engine, but leaving out the SQL stuff that duplicates 
functionality already in REBOL (think blocks and series functions). 
You may be able to access the data (a little unlikely), but it won't 
be SQLite support.

the dataflow takes care of calling any aspect which are built up 
from linked nodes.  basically, you build up a stylesheet by connecting 
nodes together and can branch off at any point, simply reusing the 
previous styles as a base... the cool thing is that the styles aren't 
absolute, you can define more than one style for a single state, 
so that a series of nodes can handle only the edge, others the color, 
yet you can include both in another style  (in my case, the base 
style has both)

btw, I am now building up a series of sample files for use as a tutorial 
as you guys ask questions and post examples.  so from now on, most 
of the question will be compiled into a great collection, used for 
an eventual tutorial!


so keep the questions comming.  independent and explicit code examples 
like the above are excellent.