/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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.
 */
package org.apache.lucene.index;

import java.io.IOException;
import org.apache.lucene.util.BytesRef;
import org.apache.lucene.util.BytesRefBuilder;
import org.apache.lucene.util.automaton.CompiledAutomaton;

/**
 * Access to the terms in a specific field. See {@link Fields}.
 *
 * @lucene.experimental
 */
public abstract class Terms {

  /** Sole constructor. (For invocation by subclass constructors, typically implicit.) */
  protected Terms() {}

  /**
   * Returns the {@link Terms} index for this field, or {@link #EMPTY} if it has none.
   *
   * @return terms instance, or an empty instance if {@code field} does not exist in this reader
   * @throws IOException if an I/O error occurs.
   */
  public static Terms getTerms(LeafReader reader, String field) throws IOException {
    Terms terms = reader.terms(field);
    if (terms == null) {
      return EMPTY;
    }
    return terms;
  }

  /** Returns an iterator that will step through all terms. This method will not return null. */
  public abstract TermsEnum iterator() throws IOException;

  /**
   * Returns a TermsEnum that iterates over all terms and documents that are accepted by the
   * provided {@link CompiledAutomaton}. If the <code>startTerm</code> is provided then the returned
   * enum will only return terms {@code > startTerm}, but you still must call next() first to get to
   * the first term. Note that the provided <code>startTerm</code> must be accepted by the
   * automaton.
   *
   * <p>This is an expert low-level API and will only work for {@code NORMAL} compiled automata. To
   * handle any compiled automata you should instead use {@link CompiledAutomaton#getTermsEnum}
   * instead.
   *
   * <p><b>NOTE</b>: the returned TermsEnum cannot seek.
   */
  public TermsEnum intersect(CompiledAutomaton compiled, final BytesRef startTerm)
      throws IOException {

    // TODO: could we factor out a common interface b/w
    // CompiledAutomaton and FST?  Then we could pass FST there too,
    // and likely speed up resolving terms to deleted docs ... but
    // AutomatonTermsEnum makes this tricky because of its on-the-fly cycle
    // detection

    // TODO: eventually we could support seekCeil/Exact on
    // the returned enum, instead of only being able to seek
    // at the start

    TermsEnum termsEnum = iterator();

    if (compiled.type != CompiledAutomaton.AUTOMATON_TYPE.NORMAL) {
      throw new IllegalArgumentException("please use CompiledAutomaton.getTermsEnum instead");
    }

    if (startTerm == null) {
      return new AutomatonTermsEnum(termsEnum, compiled);
    } else {
      return new AutomatonTermsEnum(termsEnum, compiled) {
        @Override
        protected BytesRef nextSeekTerm(BytesRef term) throws IOException {
          if (term == null) {
            term = startTerm;
          }
          return super.nextSeekTerm(term);
        }
      };
    }
  }

  /**
   * Returns the number of terms for this field, or -1 if this measure isn't stored by the codec.
   * Note that, just like other term measures, this measure does not take deleted documents into
   * account.
   */
  public abstract long size() throws IOException;

  /**
   * Returns the sum of {@link TermsEnum#totalTermFreq} for all terms in this field. Note that, just
   * like other term measures, this measure does not take deleted documents into account.
   */
  public abstract long getSumTotalTermFreq() throws IOException;

  /**
   * Returns the sum of {@link TermsEnum#docFreq()} for all terms in this field. Note that, just
   * like other term measures, this measure does not take deleted documents into account.
   */
  public abstract long getSumDocFreq() throws IOException;

  /**
   * Returns the number of documents that have at least one term for this field. Note that, just
   * like other term measures, this measure does not take deleted documents into account.
   */
  public abstract int getDocCount() throws IOException;

  /**
   * Returns true if documents in this field store per-document term frequency ({@link
   * PostingsEnum#freq}).
   */
  public abstract boolean hasFreqs();

  /** Returns true if documents in this field store offsets. */
  public abstract boolean hasOffsets();

  /** Returns true if documents in this field store positions. */
  public abstract boolean hasPositions();

  /** Returns true if documents in this field store payloads. */
  public abstract boolean hasPayloads();

  /** Zero-length array of {@link Terms}. */
  public static final Terms[] EMPTY_ARRAY = new Terms[0];

  /**
   * Returns the smallest term (in lexicographic order) in the field. Note that, just like other
   * term measures, this measure does not take deleted documents into account. This returns null
   * when there are no terms.
   */
  public BytesRef getMin() throws IOException {
    return iterator().next();
  }

  /**
   * Returns the largest term (in lexicographic order) in the field. Note that, just like other term
   * measures, this measure does not take deleted documents into account. This returns null when
   * there are no terms.
   */
  @SuppressWarnings("fallthrough")
  public BytesRef getMax() throws IOException {
    long size = size();

    if (size == 0) {
      // empty: only possible from a FilteredTermsEnum...
      return null;
    } else if (size >= 0) {
      // try to seek-by-ord
      try {
        TermsEnum iterator = iterator();
        iterator.seekExact(size - 1);
        return iterator.term();
      } catch (
          @SuppressWarnings("unused")
          UnsupportedOperationException ignored) {
        // ok
      }
    }

    // otherwise: binary search
    TermsEnum iterator = iterator();
    BytesRef v = iterator.next();
    if (v == null) {
      // empty: only possible from a FilteredTermsEnum...
      return v;
    }

    BytesRefBuilder scratch = new BytesRefBuilder();
    scratch.append((byte) 0);

    // Iterates over digits:
    while (true) {

      int low = 0;
      int high = 256;

      // Binary search current digit to find the highest
      // digit before END:
      while (low != high) {
        int mid = (low + high) >>> 1;
        scratch.setByteAt(scratch.length() - 1, (byte) mid);
        if (iterator.seekCeil(scratch.get()) == TermsEnum.SeekStatus.END) {
          // Scratch was too high
          if (mid == 0) {
            scratch.setLength(scratch.length() - 1);
            return scratch.get();
          }
          high = mid;
        } else {
          // Scratch was too low; there is at least one term
          // still after it:
          if (low == mid) {
            break;
          }
          low = mid;
        }
      }

      // Recurse to next digit:
      scratch.setLength(scratch.length() + 1);
      scratch.grow(scratch.length());
    }
  }

  /** Expert: returns additional information about this Terms instance for debugging purposes. */
  public Object getStats() throws IOException {
    StringBuilder sb = new StringBuilder();
    sb.append("impl=").append(getClass().getSimpleName());
    sb.append(",size=").append(size());
    sb.append(",docCount=").append(getDocCount());
    sb.append(",sumTotalTermFreq=").append(getSumTotalTermFreq());
    sb.append(",sumDocFreq=").append(getSumDocFreq());
    return sb.toString();
  }

  /** An empty {@link Terms} which returns no terms */
  private static final Terms EMPTY =
      new Terms() {
        @Override
        public TermsEnum iterator() throws IOException {
          return TermsEnum.EMPTY;
        }

        @Override
        public long size() throws IOException {
          return 0;
        }

        @Override
        public long getSumTotalTermFreq() throws IOException {
          return 0;
        }

        @Override
        public long getSumDocFreq() throws IOException {
          return 0;
        }

        @Override
        public int getDocCount() throws IOException {
          return 0;
        }

        @Override
        public boolean hasFreqs() {
          return false;
        }

        @Override
        public boolean hasOffsets() {
          return false;
        }

        @Override
        public boolean hasPositions() {
          return false;
        }

        @Override
        public boolean hasPayloads() {
          return false;
        }
      };
}
