ocaml-lib-devel

[Ocaml-lib-devel] Xarray try #2

[Brian H. <bh...@sp...>]

- Now using user defined resizing functions.  Surprisingly, this actually 
cleaned up the code.  Two default resizing functions are supplied- 
exponential, which doubles the array size when the number of used elements 
is greater than the array size, and halves the array size when the number 
of used elements is less the 1/4th the array size (to help prevent 
thrashing), and stepping, which adds or subtracts a given step size.

Resizers are applied as optional arguments- generally the default is 
exponential.  So you can just do:
    make len null
to get the exponential resizer, or:
    make ~resizer:(step_resizer 10) len null
to get the stepwise resizer, or:
    make ~resizer:my_resizer len null
to use your own resizer.

The only places where exponential is not the default resizer is the copy,
map, and mapi functions, which by default uses the resizer of the source
xarray (but can be overridden with a default argument as above, allowing
you to change resizer functions while copying the xarray).  The function 
invalid_resizer is an internal function which tells me to use the source 
resizer.

- Got rid of the negative index "feature"- people seemed to be mainly 
against it, and it cleaned up and simplified the code.  This also let me 
turn a bunch of let rec's into just let's.  Added a last function to 
return the last element- the API already had remove_last and append 
(insert_last) functions.  

- The .mli file now has doc comments!  Yay!  The .ml file still needs to 
be commented.

- Note that Array.append appends two whole arrays, as does List.append.  
So I changed the name to append_element, and wrote an append which appends 
an xarray.  Added a sub function.

- Added a copy function.  A set_length function was already in the API 
(changed it's name to set_length not set_len).  set_length now explicitly 
sets the array length to the given length, without calling the resizer.

- Minor enhancements- started using the Array.sub and Array.copy functions 
where usefull.

- Length is the length of the actual underlying storage array, used is the 
number of elements in that array actually being used.  I've decided on 
that nomenclature, and started sticking by it.

- Sort functions, etc. still need to be written.

Brian

Re: [Ocaml-lib-devel] Xarray try #2

[Nicolas C. <war...@fr...>]

> - Now using user defined resizing functions.  Surprisingly, this actually
> cleaned up the code.  Two default resizing functions are supplied-
> exponential, which doubles the array size when the number of used elements
> is greater than the array size, and halves the array size when the number
> of used elements is less the 1/4th the array size (to help prevent
> thrashing), and stepping, which adds or subtracts a given step size.
>
> Resizers are applied as optional arguments- generally the default is
> exponential.  So you can just do:
>     make len null
> to get the exponential resizer, or:
>     make ~resizer:(step_resizer 10) len null
> to get the stepwise resizer, or:
>     make ~resizer:my_resizer len null
> to use your own resizer.

Excellent, but since this is an "advanced feature", I suggest that you move
the resizers to the end of the mli, so they will appear at the end of the
documentation.

> - The .mli file now has doc comments!  Yay!  The .ml file still needs to
> be commented.

Does it really needs ?
I don't especially like comments in source files, they are only needed when
you're doing something very difficult to understand...

> - Length is the length of the actual underlying storage array, used is the
> number of elements in that array actually being used.  I've decided on
> that nomenclature, and started sticking by it.

Let me disagree on it :)
Since users are used to use the "length" keyword for both Array and List, it
would be better to have "length" being the number of elements and "size"
being the underlying structure size.

Last thing : renaming Xarray to Vector ?

BTW, I'm currently writting the "Enum" module (which is the "iterator" I
have been talking about) and it will be done soon.

Nicolas Cannasse

Re: [Ocaml-lib-devel] Xarray try #2

[Brian H. <bri...@ql...>]

On Tue, 15 Apr 2003, Nicolas Cannasse wrote:

> Excellent, but since this is an "advanced feature", I suggest that you move
> the resizers to the end of the mli, so they will appear at the end of the
> documentation.

No problemo.  The only reason they're first is that they're that way in 
the .ml file.

> 
> > - The .mli file now has doc comments!  Yay!  The .ml file still needs to
> > be commented.
> 
> Does it really needs ?
> I don't especially like comments in source files, they are only needed when
> you're doing something very difficult to understand...

I have been surprised at what is "intuitively obvious" one day, and 
"completely inexplicable" sometime later.  While I don't think there is 
any 'inexplicable' code in this source file, I'm a firm beleiver in better 
safe than sorry.

> 
> > - Length is the length of the actual underlying storage array, used is the
> > number of elements in that array actually being used.  I've decided on
> > that nomenclature, and started sticking by it.
> 
> Let me disagree on it :)
> Since users are used to use the "length" keyword for both Array and List, it
> would be better to have "length" being the number of elements and "size"
> being the underlying structure size.

Agreed.  And this should be mentioned in the documentation.

> 
> Last thing : renaming Xarray to Vector ?

I *hate* the name vector for resizable arrays- I do too much LinAlg.  A 
vector is a specific mathematical concept, which while it can be 
implemented as an array doesn't have to be, it can be some more 
complicated datastructure.  Consider sparse vectors.  While I'm willing to 
admit that Xarray isn't the best possible name, I like it better than 
Vector.

Brian

Re: [Ocaml-lib-devel] Xarray try #2

[Blair Z. <bl...@or...>]

Brian Hurt wrote:
> 
> On Tue, 15 Apr 2003, Nicolas Cannasse wrote:
> 
> > Excellent, but since this is an "advanced feature", I suggest that you move
> > the resizers to the end of the mli, so they will appear at the end of the
> > documentation.
> 
> No problemo.  The only reason they're first is that they're that way in
> the .ml file.
> 
> >
> > > - The .mli file now has doc comments!  Yay!  The .ml file still needs to
> > > be commented.
> >
> > Does it really needs ?
> > I don't especially like comments in source files, they are only needed when
> > you're doing something very difficult to understand...
> 
> I have been surprised at what is "intuitively obvious" one day, and
> "completely inexplicable" sometime later.  While I don't think there is
> any 'inexplicable' code in this source file, I'm a firm beleiver in better
> safe than sorry.

Agreed.  I can't believe there's a suggestion to remove documentation :)

I suggest we keep it in there.

Best,
Blair

-- 
Blair Zajac <bl...@or...>
Plots of your system's performance - http://www.orcaware.com/orca/

Re: [Ocaml-lib-devel] Xarray try #2

[Brian H. <bri...@ql...>]

On Tue, 15 Apr 2003, Blair Zajac wrote:

> > >
> > > > - The .mli file now has doc comments!  Yay!  The .ml file still needs to
> > > > be commented.
> > >
> > > Does it really needs ?
> > > I don't especially like comments in source files, they are only needed when
> > > you're doing something very difficult to understand...
> > 
> > I have been surprised at what is "intuitively obvious" one day, and
> > "completely inexplicable" sometime later.  While I don't think there is
> > any 'inexplicable' code in this source file, I'm a firm beleiver in better
> > safe than sorry.
> 
> Agreed.  I can't believe there's a suggestion to remove documentation :)

Actually, it's a suggestion not to add comments.  They aren't there yet.  
I fully intend to add them (see above comments)- at least some of them- 
while I still remember how it works.

Brian