/*
 * Copyright 2004 The Apache Software Foundation
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
using System;
namespace Lucene.Net.Search
{
	
    /// <summary>Expert: Common scoring functionality for different types of queries.
    /// <br>A <code>Scorer</code> either iterates over documents matching a query,
    /// or provides an explanation of the score for a query for a given document.
    /// <br>Document scores are computed using a given <code>Similarity</code> implementation.
    /// </summary>
    public abstract class Scorer
	{
		private Similarity similarity;
		
        /// <summary>Constructs a Scorer.</summary>
        /// <param name="similarity">The <code>Similarity</code> implementation used by this scorer.
        /// </param>
        protected internal Scorer(Similarity similarity)
		{
			this.similarity = similarity;
		}
		
		/// <summary>Returns the Similarity implementation used by this scorer. </summary>
		public virtual Similarity GetSimilarity()
		{
			return this.similarity;
		}
		
        /// <summary>Scores and collects all matching documents.</summary>
        /// <param name="hc">The collector to which all matching documents are passed through
        /// {@link HitCollector#Collect(int, float)}.
        /// <br>When this method is used the {@link #Explain(int)} method should not be used.
        /// </param>
        public virtual void  Score(HitCollector hc)
		{
			while (Next())
			{
				hc.Collect(Doc(), Score());
			}
		}
		
        /// <summary>Expert: Collects matching documents in a range.  Hook for optimization.
        /// Note that {@link #next()} must be called once before this method is called
        /// for the first time.
        /// </summary>
        /// <param name="hc">The collector to which all matching documents are passed through
        /// {@link HitCollector#Collect(int, float)}.
        /// </param>
        /// <param name="max">Do not score documents past this.
        /// </param>
        /// <returns> true if more matching documents may remain.
        /// </returns>
        protected internal virtual bool Score(HitCollector hc, int max)
        {
            while (Doc() < max)
            {
                hc.Collect(Doc(), Score());
                if (!Next())
                    return false;
            }
            return true;
        }
		
        /// <summary>Advances to the next document matching the query.</summary>
        /// <returns> true iff there is another document matching the query.
        /// <br>When this method is used the {@link #Explain(int)} method should not be used.
        /// </returns>
        public abstract bool Next();
		
        /// <summary>Returns the current document number matching the query.
        /// Initially invalid, until {@link #next()} is called the first time.
        /// </summary>
        public abstract int Doc();
		
        /// <summary>Returns the score of the current document matching the query.
        /// Initially invalid, until {@link #next()} or {@link #skipTo(int)}
        /// is called the first time.
        /// </summary>
        public abstract float Score();
		
        /// <summary>Skips to the first match beyond the current whose document number is
        /// greater than or equal to a given target.
        /// <br>When this method is used the {@link #Explain(int)} method should not be used.
        /// </summary>
        /// <param name="target">The target document number.
        /// </param>
        /// <returns> true iff there is such a match.
        /// <p>Behaves as if written: <pre>
        /// boolean skipTo(int target) {
        /// do {
        /// if (!next())
        /// return false;
        /// } while (target > doc());
        /// return true;
        /// }
        /// </pre>Most implementations are considerably more efficient than that.
        /// </returns>
        public abstract bool SkipTo(int target);
		
        /// <summary>Returns an explanation of the score for a document.
        /// <br>When this method is used, the {@link #next()}, {@link #skipTo(int)} and
        /// {@link #Score(HitCollector)} methods should not be used.
        /// </summary>
        /// <param name="doc">The document number for the explanation.
        /// </param>
        public abstract Explanation Explain(int doc);
	}
}