Rob Leslie wrote:
> On Nov 5, 2005, at 5:01 AM, Yukihiro Matsumoto wrote:
> >>   image.resize! 200, 300
> >>   image.draw do |pen|
> >>     pen.color = image.palette.find! Color.new(1.0, 0.75, 0.5)
> >
> > I don't think resize! and find! do not require bang sign in the
> > name.
>
> Actually, I was conscious of this; the non-bang Image#resize does not
> modify the receiver but returns a new image instead. Also,
> Palette#find never modifies the palette, but Palette#find! allocates
> the color if it doesn't already exist.
>
> So I didn't use the bang sign without reason, [...]


Hi Rob,

This is based on a cursory look, so forgive the inaccuracies.

IMHO, resize! is fine but find! & allocate! could be better.

You've already, perhaps, checked out other API's available
from interfaces to other languages.  Some are listed here:
http://www.boutell.com/boutell/gdmanualtest.html#gdother

( None for Ruby -- you'll rectify that with an e-mail, later :-? )

A clean-looking Lisp one I found is here:
http://www.weitz.de/cl-gd/


Always a good idea to keep an eye on the competition.

-----          -----          -----          -----          -----

> [...] but perhaps it's a bit much to have non-destructive
> image operations?

You surely wouldn't want to be doing non-destructive operations
/accidentally/ on an in-memory copy.  IOW, you might insist
that *all* operations are destructive and provide an explicit
dup/clone method to prevent excessive memory loading (?)


>     pen.color = image.palette.find! Color.new(1.0, 0.75, 0.5)

A possibility here is:

          image.palette.find_color(1.0, 0.75, 0.5, :exact, :alloc)

- where the first arg can be a Color, otherwise the first three args
are R-G-B (with the rest as options).  It's a tough call when there
are multiple options but I tend away from adding methods for various
option combinations ...

   e.g. avoid:  find_exact_color(...)
                find_color_alloc(...)
                find_exact_color_alloc(...)
                ... etc.

- when each is a variation on find_color(...).

(That may not apply to what you've written but the Lisp version
 uses the 'options' approach.)

In general, the fewer methods - the better, IMO.

I wonder if red= , green=, blue= could be improved by, say:

    rgb = (nil, 45, nil)   # ?
    rgb = (-1, 45, -1)     # ?

- presumably, setting more than one gives a gain and it's fairly
readable.
No?  - OK, I'm nowhere near as close to this as you are ;-)

Alternatives are well worth exploring to squeeze every ounce of
usability out of the API design.
(Reduces the number of moaners later, also, I expect :-)


But, hey - Thanks !!
I hope to acquire the skills to use this soon :))


daz