/*
   Wotonomy: OpenStep design patterns for pure Java applications.
   Copyright (C) 2000 Blacksmith, Inc.
   
   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Lesser General Public
   License as published by the Free Software Foundation; either
   version 2.1 of the License, or (at your option) any later version.
   
  This library 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
  Lesser General Public License for more details.
  
  You should have received a copy of the GNU Lesser General Public
  License along with this library; if not, see http://www.gnu.org
  */
  
  package net.wotonomy.foundation;
  
  /***
  * A pure java implementation of NSRange.
  * An NSRange represents a range of numbers
  * having a starting location and spanning a
  * length.
  *
  * @author michael@mpowers.net
  * @author $Author: cgruber $
  * @version $Revision: 920 $
  */
  public class NSRange implements Cloneable
  {
      /***
      * An empty range.
      */
      public static final NSRange ZeroRange = new NSRange();
      
      protected int loc;
      protected int len;
  
      /***
      * Default constructor produces an empty range.
      */
      public NSRange ()
      {
      	this( 0, 0 ); 
      }
      
      /***
      * Produces a range with the specified location and length.
      */
      public NSRange (int location, int length)
      {
      	loc = location;
  	    len = length;
      }
      
      /***
      * Produces a range that has the same location and length as 
      * the specified range.
      */
      public NSRange (NSRange aRange)
      {
      	this( aRange.location(), aRange.length() );
      }
  
      /***
      * Returns the location of this range.
      */
      public int location ()
      {
      	return loc;
      }
      
      /***
      * Returns the length of this range.
      */
      public int length ()
      {
      	return len;
      }
      
      /***
      * Returns the maximum extent of the range.  This number is 
      * one more than the last position in the range.
      */
      public int maxRange ()
      {
      	return location() + length() -1;
      }
      
      /***
      * Returns whether this is an empty range, therefore
      * whether the length is zero.
      */
      public boolean isEmpty ()
      {
      	return ( length() == 0 );
      }
     
     /***
     * Returns whether the specified location is contained
     * within this range.
     */
     public boolean locationInRange (int location)
     {
     	if ( location < location() ) return false;
 	    if ( location >= maxRange() ) return false;
 	    return true;
     }
     
     /***
     * Returns whether the specified range is equal to this range.
     */
     public boolean isEqualToRange (NSRange aRange)
     {
     	if ( aRange == null ) return false;
     	return ( ( aRange.location() == location() ) 
 		    &&   ( aRange.length() == length() ) );
     }
 
     /***
     * Returns whether the specified object is equal to this range.
 	*/
     public boolean equals (Object anObject)
     {
     	if ( anObject instanceof NSRange ) 
 	    	return isEqualToRange( (NSRange) anObject );
 		return false;
     }
 
     /***
     * Returns a hashCode. 
 	*/
     public int hashCode ()
     {
     	// TODO: Test this logic.
     	return ( location() << 2 ) & length(); // bitwise ops never my forte 
     }
 
     /***
     * Returns a string representation of this range.
 	*/
     public String toString ()
     {
     	return "[NSRange: location = " + location() 
 	    	+ "; length = " + length() + "]";
     }
 
     /***
     * Returns the union of this range and the specified range, if any.
     * Gaps are filled, so the result is the smallest starting position
     * and the largest ending position.
 	*/
     public NSRange rangeByUnioningRange (NSRange aRange)
     {
     	if ( aRange == null ) return this;
     
     	// TODO: Test this logic.    
 		int resultLoc = Math.min( this.location(), aRange.location() );
 		int resultLen = Math.max( this.location() + this.length(), 
 			aRange.location() + aRange.length() ) - resultLoc;
 		return new NSRange( resultLoc, resultLen );
     }	
 
     /***
     * Returns the intersection of this range and the specified range,
     * if any.  If no intersection, returns an empty range.
 	*/
     public NSRange rangeByIntersectingRange (NSRange aRange)
     {
     	// TODO: Test this logic.    
     	if ( ! intersectsRange( aRange ) ) return ZeroRange;
 	    int start = Math.max( this.location(), aRange.location() );
 	    int end = Math.min( this.location() + this.length(), 
 	    	aRange.location() + aRange.length() );
 		return new NSRange( start, end - start );
     }
 
     /***
     * Returns whether the specified range overlaps
     * at any point with this range.
 	*/
     public boolean intersectsRange (NSRange aRange)
     {
     	// TODO: Test this logic.    
     	if ( aRange == null ) return false;
 	    if ( ( this.location() >= aRange.location() ) 
 		&&   ( this.location() < aRange.location() + aRange.length() ) )
 			return true;
 	    if ( ( aRange.location() >= this.location() ) 
 		&&   ( aRange.location() < this.location() + this.length() ) )
 			return true;
 		return false;
     }
 
     /***
     * Returns whether this range is completely 
     * contained within the specified range.
 	*/
     public boolean isSubrangeOfRange (NSRange aRange)
     {
     	// TODO: Test this logic.    
     	if ( aRange == null ) return false;
 	    if ( ( this.location() >= aRange.location() ) 
 	    &&   ( this.maxRange() <= aRange.maxRange() ) )
 	    	return true;
 		return false;
     }
 
     /***
     * Eliminates any intersections between this range and the specified
     * range.  This produces two ranges, either of which may be empty.
     * These two ranges are returned by modifying the supplied second
     * and third parameters.
 	*/
     public void subtractRange (NSRange aRange, 
     	NSMutableRange firstResult, NSMutableRange secondResult)
     {
     	if ( aRange == null ) return;
 	    
 	    // TODO: Test this logic.
 	    // no intersection: return this and aRange without calculation
 	    if ( ! intersectsRange( aRange ) ) 
 	    { 
 	    	if ( firstResult != null )
 		    {
                 firstResult.setLocation( this.location() );
                 firstResult.setLength( this.length() );
 	    	}
 		    if ( secondResult != null )
 		    {
                 secondResult.setLocation( aRange.location() );
                 secondResult.setLength( aRange.location() );
 	    	}
 		    return;
 	    }
 	    
 	    // TODO: Test this logic.
 	    // this range is completely contained by other range
 	    if ( isSubrangeOfRange( aRange ) )
 	    { 
 			if ( firstResult != null )
 		    {
                 firstResult.setLocation( aRange.location() );
                 firstResult.setLength( this.location() - aRange.location() );
 	    	}
 		    if ( secondResult != null )
 		    {
                 secondResult.setLocation( this.maxRange() );
                 secondResult.setLength( 
 					aRange.maxRange() - this.maxRange() - 1 ); // test this
 	    	}
 		    return;
 	    }
 
 	    // TODO: Test this logic.
 	    // other range is completely contained by this range
 	    if ( aRange.isSubrangeOfRange( this ) )
 	    { 
 			if ( firstResult != null )
 		    {
                 firstResult.setLocation( this.location() );
                 firstResult.setLength( aRange.location() - this.location() );
 	    	}
 		    if ( secondResult != null )
 		    {
                 secondResult.setLocation( aRange.maxRange() );
                 secondResult.setLength( 
 					this.maxRange() - aRange.maxRange() - 1 ); // test this
 	    	}
 		    return;
 	    }
 	    
 	    // TODO: Test this logic.
 	    // ranges intersect: remove only the intersection
 	    
 	    NSRange firstRange, secondRange;
 	    if ( this.location() <= aRange.location() )
 	    {
 	    	firstRange = this;
 		    secondRange = aRange;	
 	    }
 	    else
 	    {
 	    	firstRange = aRange;
 		    secondRange = this;	
 	    }
 	    
         if ( firstResult != null )
         {
             firstResult.setLocation( firstRange.location() );
             firstResult.setLength( 
 	    		secondRange.location() - firstRange.location() );
         }
         if ( secondResult != null )
         {
             secondResult.setLocation( firstRange.maxRange() );
             secondResult.setLength(
                 secondRange.maxRange() - aRange.maxRange() - 1 ); // test this
         }
         return;
 
     }
 
     /***
     * Returns a copy of this range.
 	*/
     public Object clone ()
     {
     	return new NSRange( location(), length() );
     }
 
     /***
     * Parses a range from a string of the form "{x,y}" where
     * x is the location and y is the length.  If not parsable,
     * an IllegalArgumentException is thrown.
 	*/
     public static NSRange fromString (String aString)
     {
     	// TODO: Test this logic.    
     	try
 	    {
             java.util.StringTokenizer tokens =
                 new java.util.StringTokenizer( aString, "{,}" );
 			int loc = Integer.parseInt( tokens.nextToken() );
 			int len = Integer.parseInt( tokens.nextToken() );
 			return new NSRange( loc, len );
 	    }
 	    catch ( Exception exc )
 	    {
 	    	throw new IllegalArgumentException( exc.toString() );
 	    }
     }
     
 }
 
 /*
  * $Log$
  * Revision 1.2  2006/02/16 13:15:00  cgruber
  * Check in all sources in eclipse-friendly maven-enabled packages.
  *
  * Revision 1.1.1.1  2000/12/21 15:47:42  mpowers
  * Contributing wotonomy.
  *
  * Revision 1.3  2000/12/20 16:25:38  michael
  * Added log to all files.
  *
  *
  */