/* 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.
 */

parcel Lucy;

/**
 * A collection of Tokens.
 *
 * An Inversion is a collection of Token objects which you can add to, then
 * iterate over.
 */
public class Lucy::Analysis::Inversion inherits Clownfish::Obj {

    Token    **tokens;
    uint32_t   size;
    uint32_t   cap;
    uint32_t   cur;                   /* pointer to current token */
    bool       inverted;              /* inversion has been inverted */
    uint32_t  *cluster_counts;        /* counts per unique text */
    uint32_t   cluster_counts_size;   /* num unique texts */

    /** Create a new Inversion.
     *
     * @param seed An initial Token to start things off, which may be
     * [](@null).
     */
    public inert incremented Inversion*
    new(Token *seed = NULL);

    /** Tack a token onto the end of the Inversion.
     *
     * @param token A Token.
     */
    public void
    Append(Inversion *self, decremented Token *token);

    /** Return the next token in the Inversion until out of tokens.
     */
    public nullable Token*
    Next(Inversion *self);

    /** Reset the Inversion's iterator, so that the next call to next()
     * returns the first Token in the inversion.
     */
    public void
    Reset(Inversion *self);

    /** Assign positions to constituent Tokens, tallying up the position
     * increments.  Sort the tokens first by token text and then by position
     * ascending.
     */
    void
    Invert(Inversion *self);

    /** Return a pointer to the next group of like Tokens.  The number of
     * tokens in the cluster will be placed into `count`.
     *
     * @param count The number of tokens in the cluster.
     */
    nullable Token**
    Next_Cluster(Inversion *self, uint32_t *count);

    uint32_t
    Get_Size(Inversion *self);

    public void
    Destroy(Inversion *self);
}