/*
 * This file is part of the Poliqarp suite.
 * 
 * Copyright (C) 2004-2009 by Instytut Podstaw Informatyki Polskiej
 * Akademii Nauk (IPI PAN; Institute of Computer Science, Polish
 * Academy of Sciences; cf. www.ipipan.waw.pl).  All rights reserved.
 * 
 * This file may be distributed and/or modified under the terms of the
 * GNU General Public License version 2 as published by the Free Software
 * Foundation and appearing in the file gpl.txt included in the packaging
 * of this file.  (See http://www.gnu.org/licenses/translations.html for
 * unofficial translations.)
 * 
 * A commercial license is available from IPI PAN (contact
 * Michal.Ciesiolka@ipipan.waw.pl or ipi@ipipan.waw.pl for more
 * information).  Licensees holding a valid commercial license from IPI
 * PAN may use this file in accordance with that license.
 * 
 * This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING
 * THE WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE.
 */

/**
 * @file heap.h
 * @brief Heap of runs.
 *
 * The heap declared in this file actually stores numbers of runs in a
 * runs structure. Its root always contains the least run; a run is
 * considered to be less than another run if its current occurrence is
 * earlier.
 */

#ifndef POLIQARP_HEAP_H
#define POLIQARP_HEAP_H

#include "runs.h"

/**
 * Heap of runs.
 */
struct heap {
   int *data;           /**< Array that contains the heap. */
   size_t size;         /**< Size of the heap. */
   struct runs *runs;   /**< Collection of runs; used to compare elements. */
};

/**
 * Checks whether a heap is empty.
 * @param heap the heap to be checked.
 * @return @b true iff the heap is empty.
 */
bool heap_empty(const struct heap *heap);

/**
 * Allocates memory for a heap.
 * @param heap the heap to be created.
 * @param runs the underlying collection of runs.
 */
void heap_create(struct heap *heap, struct runs *runs);

/**
 * Deallocates all resources used by this heap.
 * @param heap the heap to be destroyed.
 */
void heap_destroy(struct heap *heap);

/** 
 * Remove the run with the earliest occurrence from the heap 
 * and return it.
 * @param heap the heap to extract the element from.
 * @return number of the least run.
 */
int heap_extract_min(struct heap *heap);

/**
 * Insert a run in the heap.
 * @param heap the heap to operate on.
 * @param i number of the run to be inserted.
 */
void heap_insert(struct heap *heap, int i);

#endif /* POLIQARP_HEAP_H */
