craterdog.collections.Dictionary 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 craterdog.collections.abstractions.Collection;
import org.slf4j.ext.XLogger;
import org.slf4j.ext.XLoggerFactory;


/**
 * This collection class is a convenience class that implements a Map whose keys
 * are always of type String.  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 the value in the association.
 */
public final class Dictionary extends Map {

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


    /**
     * This constructor creates a new empty dictionary.
     */
    public Dictionary() {
        super();
    }


    /**
     * This constructor creates a new dictionary using the specified key and value arrays.  The
     * number of keys must equal the number of values or an exception is thrown.
     *
     * @param keys The array of keys that should be used to create the dictionary.
     * @param values The array of values that should be used to create the dictionary.
     */
    public Dictionary(String[] keys, V[] values) {
        super(keys, values);
    }


    /**
     * This constructor creates a new dictionary using the specified keys and values.  The
     * number of keys must equal the number of values or an exception is thrown.
     *
     * @param keys The keys that should be used to create the dictionary.
     * @param values The values that should be used to create the dictionary.
     */
    public Dictionary(Collection keys, Collection values) {
        super(keys, values);
    }


    /**
     * This constructor creates a new dictionary using the elements provided in the specified map.
     *
     * @param elements The dictionary containing the key-value pairs to be mapped.
     */
    public Dictionary(Map elements) {
        super(elements);
    }


    /**
     * This constructor creates a new dictionary using the elements provided in a java map.
     *
     * @param elements The java map containing the key-value pairs to be mapped.
     */
    public Dictionary(java.util.Map elements) {
        super(elements);
    }


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


    /**
     * This function returns a new dictionary that contains the all the associations from
     * both the specified dictionaries.
     *
     * @param  The type of value contained in the dictionaries.
     * @param dictionary1 The first dictionary whose elements are to be added.
     * @param dictionary2 The second dictionary whose elements are to be added.
     * @return The resulting dictionary.
     */
    static public  Dictionary concatenation(Dictionary dictionary1, Dictionary dictionary2) {
        logger.entry(dictionary1, dictionary2);
        Dictionary result = new Dictionary<>(dictionary1);
        result.addElements(dictionary2);
        logger.exit(result);
        return result;
    }


    /**
     * This function returns a new dictionary that contains only the associations with
     * the specified keys.
     *
     * @param  The type of value contained in the dictionaries.
     * @param dictionary The dictionary whose elements are to be reduced.
     * @param keys The set of keys for the associates to be saved.
     * @return The resulting dictionary.
     */
    static public  Dictionary reduction(Dictionary dictionary, Set keys) {
        logger.entry(dictionary, keys);
        Dictionary result = new Dictionary<>();
        for (String key : keys) {
            V value = dictionary.getValue(key);
            if (value != null) {
                logger.debug("Associating key: {} with value: {}", key, value);
                Association association = new Association<>(key, value);
                result.addElement(association);
            }
        }
        logger.exit(result);
        return result;
    }

}