Queque.

//
// Created by Julio Tentor <jtentor@fi.unju.edu.ar>
// Modificado y Traducido al Español por Mario Ariel Fernando Cabana <42268639@fi.unju.edu.ar>
//

/*
public interface Queue<E>
extends Collection<E>

Una colección diseñada a contener elementos antes de su procesamiento.
Ademas de una colección con operaciones basicas, las colas proveen un encaje adicional
extracciones, y operaciones de inspección. Cada uno de esos metodos se presentan en
dos formas: uno arroja una excepción en caso de que la operación falle, la otra
retorna un valor especial (ya sea nulo o falso, dependiendo de la operación).

La forma mas tardia de insertar una operación es designandola especificamente por uso
con implementaciones de cola de capacidad restringida; en cuanto más implementaciones,
las operaciones de inserción no podran fallar.

Las Colas tipicamente, pero no necesariamente, ordenan sus elementos por medio
de FIFO (first-in-first-out). Al rededor de excepciones que son prioridad de la cola,
las cuales ordenan los elementos de acuerdo a un comparador suministrado, u el ordenamiento natural
de los elementos, y colas LIFO (o pilas) las cuales ordenan los elementos en
LIFO (last-in-first-out). Sea cual sea el ordenamiento usado, la cabeza de la cola
es el elemnto que podria ser removido por un llamado a remove() o poll().
Dado una cola FIFO, todo nuevo elemento es insertado en la cola, tail, de la cola.
Otro tipo de colas pueden usar diferentes reglas de colocación.
Cada implementación de cola debe especificar estas propiedades de ordenamiento.

EL metodo Offer inserta un elemento si es posible, de otro modo este retorna
falso. Estas difieren del metodo Collection.add, el cual puede fallar para
agregar un elemento solo por un arrojamiento de una excepción inespecificada. El metodo offer
esta designado para usarse cuando una falla es normal, más que una ocurrencia
excepcional, por ejemplo, en colas fixed-capacity (o "bounded").

Los metodos remove() y poll() remueven y retornan la cabeza de la cola.
Precisamente este elemento es removido de la cola es una función de la
norma de ordenamiento cola, el mismo difiere de la implementación to
implementation. Los metodos remove() y poll() difieren solo en su
comportamiento cuando la cola se encuentra vacia: the remove() arroja una
excepción, mientras que poll() retorna null.

Los metodos element() and peek() retornan, pero no remueven, la cabeza de
la cola.

La interfaz de la cola no define el bloqueo de sus metodos, los cuales
son comunes el la programación concurrida. estos metodos, esperan por
elementos a aparecer o por espacios que estaran disponibles, estas son definidas
en la interfaz BlockingQueue, que extiende esta interfaz.

Las implementaciones de la cola generalmente no permiten la inserción de elemento nulos,
asi tambien como alguna impleentacion, como ser LinkedList, no permiten la insercion de
nulos. Aun que en implementaciones que lo permiten, el nulo no debe ser insertado en la cola,
como nulo tambien es usado un valor de retorno especial por el metodoo poll que indica
que la cola contiene no elementos.

Las implementaciones de la cola generalmente no definen elemento-basado en versiones de
metodos iguales y hashCode pero mas alla de eso e inherente la identidad basada en
versiones de clase Object, porque la igualdad del elemento-basado no es
siempre bien definida por colas con el mismo elemento pero diferente ordenamiento
de propiedades.

esta interfaz es un miembro de the Java Collections Framework.



from https://docs.oracle.com/en/java/javase/13/docs/api/java.base/java/util/Queue.html
from https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/util/Queue.html
from https://docs.oracle.com/en/java/javase/15/docs/api/java.base/java/util/Queue.html

 */


import java.util.Arrays;

public class Cola<T> {

    //region Constantes

    private final static Integer defaulDimension = 10;

    //endregion

    //region Atributos

    private T [] data;
    private int head;
    private int tail;
    private int count;

    //endregion

    //region Constructores

    public Cola() {
        this(Cola.defaulDimension);
    }
    public Cola(int dimension) {
        this.data = (T[]) new Object[dimension];
        this.head = 0;
        this.tail = 0;
        this.count = 0;
    }
    //endregion

    //region Metodos Internos de la Cola
    private int next(int pos) {
        if (++pos >= this.data.length) {
            pos = 0;
        }
        return pos;
    }
    //endregion


    //region Metodos de la Cola

    // Operación EnQueue en la teoría de Estructura de Datos
    //
    // Inserta un elemento especificado en la cola si esto es posible de hacer entonces
    // inmediatamente sin violar las restricciones, retorna verdadero sobre
    // el exito y arroja una IllegalStateException si no hay espacio concurrentemente
    // disponible.
    public boolean add(T element) {

        if (this.size() >= this.data.length) {
            throw new IllegalStateException("Cola llena ...");
        }

        this.data[this.tail] = element;
        this.tail = this.next(this.tail);
        ++this.count;

        return true;
    }

    // Operación peek en la teoría de Estructura de Datos
    //
    // Recupera, pero no remueve, la cabeza de la cola. Este difiere del peek
    // solo en que este arroja una excepción si la cola esta vacia.
    public T element() {

        if (this.size() <= 0) {
            throw new IllegalStateException("Cola vacía ...");
        }

        return this.data[this.head];
    }

    // Operación EnQueue en la teoría de Estructura de Datos
    //
    // Inserta un elemento especificado en la cola si si esto es posible de hacer entonces
    // inmediatamente sin violar las restricciones. Cuando se usa una
    // capacidad-restringidad en cola, este metodo prefiere generalmente agregar (E),
    // el cual puede fallar al insertar un elemento solo por arrojar una excepción.
    public boolean offer(T element) {

        if (this.size() >= this.data.length) {
            return false;
        }

        this.data[this.tail] = element;
        this.tail = this.next(this.tail);
        ++this.count;

        return true;
    }

    // Recupera, pero no remueve, la cabeza de la cola, o retorna nulo si
    // la cola esta vacia.
    public T peek() {
        if (this.size() <= 0) {
            return null;
        }

        return this.data[this.head];
    }

    // Operación DeQueue en la teoría de Estructura de Datos
    //
    // Recupera y remueve la cabeza de la cola, o retorna nulo si la cola
    // esta vacia.
    public T pool() {
        if (this.size() <= 0) {
            return null;
        }

        T result = this.data[this.head];
        this.head = this.next(this.head);
        --this.count;

        return result;
    }

    // Operación DeQueue en la teoría de Estructura de Datos
    //
    // Recupera y remueve la cabeza de la cola. Este difiere del poll()
    // solo en que este arroja una excepción si la cola esta vacia.
    public T remove() {
        if (this.size() <= 0) {
            throw new IllegalStateException("Cola vacía ...");
        }

        T result = this.data[this.head];
        this.head = this.next(this.head);
        --this.count;

        return result;
    }
    //endregion


    //region Override Object basic methods

    @Override
    public String toString() {

        if (this.size() <=0) {
            return "";
        }

        // from https://docs.oracle.com/en/java/javase/15/docs/api/java.base/java/lang/StringBuilder.html
        StringBuilder sb = new StringBuilder();
        sb.append("[" + this.data[this.head].toString());

        for (int cta = 1, pos = this.next(this.head); cta < this.size(); ++cta, pos = this.next(pos)) {
            sb.append(", " + this.data[pos].toString());
        }

        sb.append("]");
        return sb.toString();
    }
    //endregion


    //region Metodos de la Colleccion

    public boolean isEmpty() {
        return this.count <= 0;
    }

    public int size() {
        return this.count;
    }

    public Object[] toArray() {
        Object[] result = new Object[this.count];
        for(int i = 0, pos = this.head, cta = this.size(); cta > 0; ++i, pos = this.next(pos), --cta) {
            result[i] = this.data[pos];
        }
        return result;
    }
    //endregion


    //region Caso Ejemplo b) Methods

    public static Cola<Object> union(Cola<?> stack1, Cola<?> stack2) {

        Cola<Object> result = new Cola<Object>(stack1.size() + stack2.size());

        for(int pos = stack1.head, cta = stack1.size(); cta > 0; pos = stack1.next(pos), --cta) {
            result.offer( stack1.data[pos] );
        }
        for(int pos = stack2.head, cta = stack2.size(); cta > 0; pos = stack2.next(pos), --cta) {
            result.offer( stack2.data[pos] );
        }

        return result;
    }

    public Cola<Object> union(Cola<?> stack2) {
        return Cola.union(this, stack2);
    }
    //endregion

}