[sword-devel] Feature Complete Perl Interface

[Troy A. Griffitts]

> Hmm.  So what you're saying is, even if I get a whole other SWKey object (as I am doing in that
> example--it's not just a reference, it's a whole SWKey), that object is tied to whatever the
> current key is in SWModule?

OK, I'm messed up.  I should've taken more time to review your code
snippet.  New answer...


SWModule::Key()  DOES return a reference to the internal key of an
object, but you are assigning it to an SWKey variable (NOT an SWKey &),
so you don't have to worry about your key reference being invalid.  The
contents are simply copied into your new SWKey variable.

Now, having said this, since you're assigning it to an SWKey variable,
you will lose the subclass specialization and functionality of the
specific key type of the module: i.e. VerseKey for a Bible module. 
SWKey objects do all they can to compare to eachother, and that is
merely a strcmp.

SWModule::CreateKey() will give you a specialized key type for that
module.  I would recommend the following code:

int VerseIterator::_verse_greater(char * verse1, char * verse2) {
	SWKey *key1, *key2;
	int retVal;

	key1 = module->CreateKey();
	key2 = module->CreateKey();

	*key1 = verse1;
	*key2 = verse2;

	retVal = *key1 > *key2;

	delete key1;
	delete key2;

	return retVal;
}



> The way I am doing this is, I store a VerseKey in my Iterator class.
> Whenever someone accesses the iterator, I do these steps:
> 
> module->SetKey(key);
> do my thing (possibly a *module++ or *module--)
> key = module->Key(); (if I changed anything)
> 
> For instance, here is my implementation of next():
> 
> int VerseIterator::next(int how_far) {
>         if(key == key.UpperBound()) {
>                 return 0;
>         }
>         module->SetKey(key);
>         (*module) += how_far;
>         key = module->Key();
>         return 1;
> }

I'm assuming this is verse specific, so you are storing a VerseKey
object, and not merely an SWKey *, which would make it not verse
specific.

Again, I might suggest using: SWKey *key = module->CreateKey() to get a
specialized key object for your Iterator object.

Then next might look something like:

int Iterator::next(int how_far) {
	module->SetKey(*key);
        (*module) += how_far;
	if (module.Error()) {
		return 0;	// assuming you really mean 0 to be a failure and not sucess
        *key = module->Key();
        return 1;
}


> Am I doing this wrong?

No, in fact I'm very impress with your grasp on the API in such a short
time.  You are very talented.


> I am aware that key supposedly supports adding and subtracting directly,
> but my experience so far has been that it didn't do anything ... again,
> I could be using the system wrong and probably am :)

Well, VerseKey know how to -- and ++, but SWKey does not.  The above
code is safer, though, as it will work for Bibles, commentaries,
lexicons/dictionaries/daily reading modules, etc.  The ++ and --, etc.,
will be specific to the module itself, and not just the general key
type.


Again, hope this helps and makes sense.  Thanks again for all your
work!  It's exciting!

	-Troy.