craterdog.collections.Bag Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of java-collection-framework Show documentation
A set of interfaces and classes that define a Java collection framework.
There is a newer version: 3.18
Show newest version
/************************************************************************
 * Copyright (c) Crater Dog Technologies(TM).  All Rights Reserved.     *
 ************************************************************************
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.        *
 *                                                                      *
 * This code is free software; you can redistribute it and/or modify it *
 * under the terms of The MIT License (MIT), as published by the Open   *
 * Source Initiative. (See http://opensource.org/licenses/MIT)          *
 ************************************************************************/
package craterdog.collections;

import com.fasterxml.jackson.annotation.JsonCreator;
import com.fasterxml.jackson.annotation.JsonValue;
import craterdog.collections.abstractions.*;
import java.util.Comparator;
import org.slf4j.ext.XLogger;
import org.slf4j.ext.XLoggerFactory;


/**
 * This collection class implements an ordered collection that allows duplicate elements.  The
 * implementation dynamically scales up and down the size of the underlying data structures as
 * the number elements changes over time.
 *
 * @author Derk Norton
 * @param  The type of element managed by the collection.
 */
public class Bag extends OrderedCollection {

    static private final XLogger logger = XLoggerFactory.getXLogger(Bag.class);


    /**
     * This constructor creates a new empty bag with no comparator function.
     */
    public Bag() {
        super(true);
    }


    /**
     * This constructor creates a new bag with no comparator function and seeds
     * it with the elements from the specified array.
     *
     * @param elements The elements to be used to seed the new bag.
     */
    @JsonCreator
    public Bag(E[] elements) {
        this(elements, null);
    }


    @JsonValue
    @Override
    public E[] toArray() {
        return super.toArray();
    }


    /**
     * This constructor creates a new bag with no comparator function and seeds
     * it with the elements from the specified collection.
     *
     * @param elements The elements to be used to seed the new bag.
     */
    public Bag(Iterable elements) {
        this(elements, null);
    }


    /**
     * This constructor creates a new bag with the specified comparator function.
     *
     * @param comparator The comparator to be used to compare two elements during ordering.
     */
    public Bag(Comparator comparator) {
        super(true, comparator);
    }


    /**
     * This constructor creates a new bag with the specified comparator function and seeds
     * it with the elements from the specified array.
     *
     * @param elements The elements to be used to seed the new bag.
     * @param comparator The comparator to be used to compare two elements during ordering.
     */
    public Bag(E[] elements, Comparator comparator) {
        super(elements, true, comparator);
    }


    /**
     * This constructor creates a new bag with the specified comparator function and seeds
     * it with the elements from the specified collection.
     *
     * @param elements The elements to be used to seed the new bag.
     * @param comparator The comparator to be used to compare two elements during ordering.
     */
    public Bag(Iterable elements, Comparator comparator) {
        super(elements, true, comparator);
    }


    @Override
    @SuppressWarnings("unchecked")
    public Bag copy() {
        return (Bag) super.copy();
    }


    /**
     * This function returns a new bag that contains the all the elements from
     * both the specified bags.
     *
     * @param  The type of element contained in the bags.
     * @param bag1 The first bag whose elements are to be added.
     * @param bag2 The second bag whose elements are to be added.
     * @return The resulting bag.
     */
    static public  Bag aggregate(Bag bag1, Bag bag2) {
        logger.entry(bag1, bag2);
        Bag result = new Bag<>(bag1);
        result.addElements(bag2);
        logger.exit(result);
        return result;
    }


    /**
     * This function returns a new bag that contains the elements that are
     * in the first bag but not contained in the second bag specified.
     *
     * @param  The type of element contained in the bags.
     * @param bag1 The bag whose elements are to be removed.
     * @param bag2 The bag whose elements are to be removed.
     * @return The resulting bag.
     */
    static public  Bag difference(Bag bag1, Bag bag2) {
        logger.entry(bag1, bag2);
        Bag result = new Bag<>(bag1);
        result.removeElements(bag2);
        logger.exit(result);
        return result;
    }

}