From 8891b04598c3ffd7d67c8012600451b2febfb0b5 Mon Sep 17 00:00:00 2001 From: Danila Fedorin Date: Fri, 4 Aug 2017 11:24:07 -0700 Subject: [PATCH] Add comments to all the pi-related stuff. --- .../abacus/plugin/NumberImplementation.java | 39 +++++++++++++++ .../java/org/nwapw/abacus/plugin/Plugin.java | 35 +++++++++++++- .../nwapw/abacus/plugin/PluginManager.java | 47 +++++++++++++++++++ .../nwapw/abacus/plugin/StandardPlugin.java | 6 +++ 4 files changed, 126 insertions(+), 1 deletion(-) diff --git a/src/main/java/org/nwapw/abacus/plugin/NumberImplementation.java b/src/main/java/org/nwapw/abacus/plugin/NumberImplementation.java index 60e02c6..66e2dd2 100644 --- a/src/main/java/org/nwapw/abacus/plugin/NumberImplementation.java +++ b/src/main/java/org/nwapw/abacus/plugin/NumberImplementation.java @@ -6,31 +6,70 @@ import java.util.HashMap; import java.util.Map; import java.util.function.Function; +/** + * A class that holds data about a number implementation. + */ public abstract class NumberImplementation { + /** + * The list of paths through which this implementation can be promoted. + */ protected Map, Function> promotionPaths; + /** + * The implementation class for this implementation. + */ private Class implementation; + /** + * The priority of converting into this number implementation. + */ private int priority; + /** + * Creates a new number implementation with the given data. + * @param implementation the implementation class. + * @param priority the priority, higher -> more likely to be converted into. + */ public NumberImplementation(Class implementation, int priority){ this.implementation = implementation; this.priority = priority; promotionPaths = new HashMap<>(); } + /** + * Gets the list of all promotion paths this implementation can take. + * @return the map of documentation paths. + */ public final Map, Function> getPromotionPaths(){ return promotionPaths; } + /** + * Gets the implementation class used by this implementation. + * @return the implementation class. + */ public final Class getImplementation(){ return implementation; } + /** + * Gets the priority of this number implementation. + * @return the priority. + */ public final int getPriority(){ return priority; } + /** + * Abstract function to create a new instance from a string. + * @param string the string to create a number from. + * @return the resulting number. + */ public abstract NumberInterface instanceForString(String string); + + /** + * Get the instance of pi with the given implementation. + * @return pi + */ public abstract NumberInterface instanceForPi(); } diff --git a/src/main/java/org/nwapw/abacus/plugin/Plugin.java b/src/main/java/org/nwapw/abacus/plugin/Plugin.java index fbc4853..3a0ed31 100644 --- a/src/main/java/org/nwapw/abacus/plugin/Plugin.java +++ b/src/main/java/org/nwapw/abacus/plugin/Plugin.java @@ -73,6 +73,11 @@ public abstract class Plugin { return operators.keySet(); } + /** + * Gets the list of number implementations provided by this plugin. + * + * @return the list of registered number implementations. + */ public final Set providedNumberImplementations(){ return numberImplementations.keySet(); } @@ -97,6 +102,12 @@ public abstract class Plugin { return operators.get(operatorName); } + /** + * Gets the number implementation under the given name. + * + * @param name the name of the number implementation to look up. + * @return the number implementation associated with that name, or null if the plugin doesn't provide it. + */ public final NumberImplementation getNumberImplementation(String name){ return numberImplementations.get(name); } @@ -146,6 +157,12 @@ public abstract class Plugin { operators.put(name, operator); } + /** + * To be used in load(). Registers a new number implementation with the plugin. + * This makes it accessible to the plugin manager. + * @param name the name of the implementation. + * @param implementation the actual implementation class to register. + */ protected final void registerNumberImplementation(String name, NumberImplementation implementation){ numberImplementations.put(name, implementation); } @@ -174,12 +191,28 @@ public abstract class Plugin { return manager.operatorFor(name); } + /** + * Searches the PluginManager for the given number implementation + * name. This can be used by the plugins internally in order to find + * implementations that they do not provide. + * + * @param name the name for which to search. + * @return the resulting number implementation, or null if none was found. + */ protected final NumberImplementation numberImplementationFor(String name){ return manager.numberImplementationFor(name); } + /** + * Searches the plugin manager for a Pi value for the given number implementation. + * This is done so that number implementations with various degrees of precision + * can provide their own pi values, without losing said precision by + * promoting NaiveNumbers. + * @param forClass the class to which to find the pi instance. + * @return the pi value for the given class. + */ protected final NumberInterface getPi(Class forClass){ - return manager.interfaceImplementationFor(forClass).instanceForPi(); + return manager.piFor(forClass); } /** diff --git a/src/main/java/org/nwapw/abacus/plugin/PluginManager.java b/src/main/java/org/nwapw/abacus/plugin/PluginManager.java index 9c98dfd..0d45964 100644 --- a/src/main/java/org/nwapw/abacus/plugin/PluginManager.java +++ b/src/main/java/org/nwapw/abacus/plugin/PluginManager.java @@ -31,8 +31,20 @@ public class PluginManager { * that is, found in a plugin and returned. */ private Map cachedOperators; + /** + * The list of number implementations that have + * been cached, that is, found in a plugin and returned. + */ private Map cachedNumberImplementations; + /** + * The list of number implementations that have been + * found by their implementation class. + */ private Map, NumberImplementation> cachedInterfaceImplementations; + /** + * The pi values for each implementation class that have already been computer. + */ + private Map, NumberInterface> cachedPi; /** * List of all functions loaded by the plugins. */ @@ -41,6 +53,9 @@ public class PluginManager { * List of all operators loaded by the plugins. */ private Set allOperators; + /** + * List of all the number implementations loaded by the plugins. + */ private Set allNumberImplementations; /** * The list of plugin listeners attached to this instance. @@ -57,6 +72,7 @@ public class PluginManager { cachedOperators = new HashMap<>(); cachedNumberImplementations = new HashMap<>(); cachedInterfaceImplementations = new HashMap<>(); + cachedPi = new HashMap<>(); allFunctions = new HashSet<>(); allOperators = new HashSet<>(); allNumberImplementations = new HashSet<>(); @@ -116,11 +132,21 @@ public class PluginManager { return searchCached(plugins, cachedOperators, Plugin::providedOperators, Plugin::getOperator, name); } + /** + * Gets the number implementation under the given name. + * @param name the name of the implementation. + * @return the implementation. + */ public NumberImplementation numberImplementationFor(String name){ return searchCached(plugins, cachedNumberImplementations, Plugin::providedNumberImplementations, Plugin::getNumberImplementation, name); } + /** + * Gets the number implementation for the given implementation class. + * @param name the class for which to find the implementation. + * @return the implementation. + */ public NumberImplementation interfaceImplementationFor(Class name){ if(cachedInterfaceImplementations.containsKey(name)) return cachedInterfaceImplementations.get(name); NumberImplementation toReturn = null; @@ -138,6 +164,22 @@ public class PluginManager { return toReturn; } + /** + * Gets the mathematical constant pi for the given implementation class. + * @param forClass the class for which to find pi. + * @return pi + */ + public NumberInterface piFor(Class forClass){ + if(cachedPi.containsKey(forClass)) return cachedPi.get(forClass); + NumberImplementation implementation = interfaceImplementationFor(forClass); + NumberInterface generatedPi = null; + if(implementation != null){ + generatedPi = implementation.instanceForPi(); + } + cachedPi.put(forClass, generatedPi); + return generatedPi; + } + /** * Adds an instance of Plugin that already has been instantiated. * @@ -214,6 +256,11 @@ public class PluginManager { return allOperators; } + /** + * Gets all the number implementations loaded by the Plugin Manager. + * + * @return the set of all implementations that were loaded. + */ public Set getAllNumberImplementations(){ return allNumberImplementations; } diff --git a/src/main/java/org/nwapw/abacus/plugin/StandardPlugin.java b/src/main/java/org/nwapw/abacus/plugin/StandardPlugin.java index 3dc2b28..0c0ab01 100755 --- a/src/main/java/org/nwapw/abacus/plugin/StandardPlugin.java +++ b/src/main/java/org/nwapw/abacus/plugin/StandardPlugin.java @@ -306,6 +306,9 @@ public class StandardPlugin extends Plugin { } }; + /** + * The implementation for double-based naive numbers. + */ public static final NumberImplementation IMPLEMENTATION_NAIVE = new NumberImplementation(NaiveNumber.class, 0) { @Override public NumberInterface instanceForString(String string) { @@ -318,6 +321,9 @@ public class StandardPlugin extends Plugin { } }; + /** + * The implementation for the infinite-precision BigDecimal. + */ public static final NumberImplementation IMPLEMENTATION_PRECISE = new NumberImplementation(PreciseNumber.class, 0) { @Override public NumberInterface instanceForString(String string) {