// ###########       FROM SVN REVISION 2644

/******************************************************************************
 *  swkey.h	- code for base class 'swkey'.  swkey is the basis for all
 *				types of keys for indexing into modules (e.g. verse, word,
 *				place, etc.)
 *
 * $Id: swkey.h 2324 2009-04-20 18:40:15Z scribe $
 *
 * Copyright 1998 CrossWire Bible Society (http://www.crosswire.org)
 *	CrossWire Bible Society
 *	P. O. Box 2528
 *	Tempe, AZ  85280-2528
 *
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the
 * Free Software Foundation version 2.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 */

package org.crosswire.sword.keys;

import org.crosswire.sword.mgr.LocaleMgr;
import org.crosswire.sword.mgr.SWLocale;

/** SWKey is used for positioning an SWModule to a specific entry.
 *	It always represents a possible location into a module and can additionally represent
 *	a domain of entries (e.g. "John 3:16" in the domain "John 1:1 - Mark 5:25")
 */
public class SWKey implements Comparable<SWKey> {
	public static final char KEYERR_OUTOFBOUNDS = 1;
	public static final int TOP = 1;
	public static final int BOTTOM = 2;

	static class LocaleCache {
		String name;
		SWLocale locale;
		LocaleCache() {
			name = null;
			locale = null;
		}
	};
	
	private static LocaleCache localeCache = new LocaleCache();
	// for caching; don't use directly, call getPrivateLocale()
	private SWLocale locale;


	long index;
	void init() {
		boundSet = false;
		locale = null;
		localeName = null;
		setLocale(LocaleMgr.getSystemLocaleMgr().getDefaultLocaleName());
	}

	protected String keytext;
	protected String rangeText;
	protected boolean boundSet;
	protected boolean persist;
	protected char error;

	protected String localeName;


	// misc pointer for whatever
	public Object userData;

	/** initializes instance of SWKey from a string
	 * All keys can be reduced to a string representation which should be able
	 *	to be used to again set the key to the same position
	 * @param ikey string to use for initializing this new key
	 */
	public SWKey(String ikey) {
		init();
		index     = 0;
		persist   = false;
		keytext   = null;
		rangeText = null;
		error     = 0;
		userData  = 0;
		keytext   = ikey;
	}
	public SWKey() { this((String)null); }

	/** Copy Constructor
	 * @param k The SWKey object to copy.
	 */
	public SWKey(SWKey k) {
		init();
		localeName = k.localeName;
		index     = k.index;
		persist   = k.persist;
		userData  = k.userData;
		keytext   = null;
		rangeText = null;
		error     = k.error;
		setText(k.getText());
	}


	public void setError(char err) { error = err; }


	public void positionFrom(SWKey ikey) { copyFrom(ikey); }

	public String getShortText() { return getText(); }
	public boolean isBoundSet() { return boundSet; }
	public void clearBound() { boundSet = false; }


	/** test equality of this SWKey object's position with another SWKey
	 * @param ikey key to compare with this one
	 * @return true if the key positions are equal
	 */
	public boolean equals(SWKey ikey) { return compare(ikey) == 0; }


	/** Whether or not this key can be ++ -- incremented
	 */
	public boolean isTraversable() { return false; }

	public String getLocale() { return localeName; }
	public void setLocale(String name) { localeName = name; locale = null; } // this will force an on demand lookup of our locale

	
	/** Use this function to get an index position within a module.
	 */
	public long getIndex() { return index; }

	
	/** See documentation for @ref setIndex()
	 */
	public void setIndex(long iindex) { index = iindex; }


	/** Returns a new exact clone of this SWKey object.  This allocates
	 * a new SWKey which must be deleted by the caller
	 * @return new clone of this key
	 */
	public SWKey clone() {
		return new SWKey(this);
	}



/******************************************************************************
 * SWKey::Persist - Gets whether this object itself persists within a
 *			module that it was used to setKey or just a copy.
 *			(1 - persists in module; 0 - a copy is attempted
 *
 * RET:	value of persist
 */

	public boolean isPersist() {
		return persist;
	}


/******************************************************************************
 * SWKey::getPrivateLocale - Gets a real locale object from our name
 *
 * RET:	locale object associated with our name
 */

	protected SWLocale getPrivateLocale() {
		if (locale == null) {
			if ((localeCache.name == null) || (!localeCache.name.equals(localeName))) {
				localeCache.name = localeName;
				// this line is the entire bit of work we're trying to avoid with the cache
				// worth it?  compare time examples/cmdline/search KJV "God love world" to
				// same with this method reduced to:
				// if (!local) local = ... (call below); return locale;
				localeCache.locale = LocaleMgr.getSystemLocaleMgr().getLocale(localeName);
			}
			locale = localeCache.locale;
		}
		return locale;
	}


/******************************************************************************
 * SWKey::Persist - Set/gets whether this object itself persists within a
 *			module that it was used to setKey or just a copy.
 *			(1 - persists in module; 0 - a copy is attempted
 *
 * ENT:	ipersist - value which to set persist
 *		[-1] - only get
 *
 * RET:	value of persist
 */

	public void setPersist(boolean ipersist) {
		persist = ipersist;
	}


/******************************************************************************
 * SWKey::popError - Gets and clears error status
 *
 * RET:	error status
 */

	public char popError() {
		char retval = error;
		error = 0;
		return retval;
	}


/** Sets this SWKey with a character string
 * @param ikey string used to set this key
 */

	public void setText(String ikey) {
		keytext = ikey;
	}


/** Copies as much info (position, range, etc.) as possible from another SWKey object
 * @param ikey other SWKey object from which to copy
 */

	public void copyFrom(SWKey ikey) {
		// not desirable	Persist(ikey.Persist());
		setLocale(ikey.getLocale());
		setText(ikey.getText());
	}


/** returns string representation of this key
 */

	public String getText() {
		return keytext;
	}


/******************************************************************************
 * SWKey::getRangeText - returns parsable range text for this key
 */

	public String getRangeText() {
		rangeText = keytext;
		return rangeText;
	}


/******************************************************************************
 * SWKey::getOSISRefRangeText - returns parsable range text for this key
 */

	public String getShortRangeText() {
		return getRangeText();
	}



/******************************************************************************
 * SWKey::getOSISRefRangeText - returns parsable range text for this key
 */

	public String getOSISRefRangeText() {
		return getRangeText();
	}

/** Compares this key object to another SWKey object
 * @param ikey key to compare with this one
 * @return >0 if this key is greater than compare key;
 *	<0 if this key is smaller than compare key;
 *	0 if the keys are the same
 */
	
	public int compare(SWKey ikey) {
		return this.getText().compareTo(ikey.getText());
	}


/******************************************************************************
 * SWKey::setPosition(SW_POSITION)	- Positions this key if applicable
 */

	public void setPosition(int p) {
		switch (p) {
		case TOP:
	//		*this = "";
			break;
		case BOTTOM:
	//		*this = "zzzzzzzzz";
			break;
		} 
	}


/** Increments key a number of entry positions
 * This is only valid if isTraversable is true
 * @param steps Number of entries to jump forward
 */
	
	public void increment() { increment(1); }
	public void increment(int i) {
		error = KEYERR_OUTOFBOUNDS;
	}


/** Decrements key a number of entry positions
 * This is only valid if isTraversable is true
 * @param steps Number of entries to jump backward
 */

	public void decrement() { decrement(1); }
	public void decrement(int i) {
		error = KEYERR_OUTOFBOUNDS;
	}
	
	@Override
	public int compareTo(SWKey o) {
		return compare(o);
	}

}