From d9aa9855f874f80ddc629c3c7179c00108991c9e Mon Sep 17 00:00:00 2001 From: David Roazen Date: Wed, 24 Oct 2012 15:29:13 -0400 Subject: [PATCH] Better comments in NestedIntegerArray --- .../utils/collections/NestedIntegerArray.java | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/public/java/src/org/broadinstitute/sting/utils/collections/NestedIntegerArray.java b/public/java/src/org/broadinstitute/sting/utils/collections/NestedIntegerArray.java index 9f1eb546d..c83de8ec7 100755 --- a/public/java/src/org/broadinstitute/sting/utils/collections/NestedIntegerArray.java +++ b/public/java/src/org/broadinstitute/sting/utils/collections/NestedIntegerArray.java @@ -89,6 +89,20 @@ public class NestedIntegerArray { return (T)myData[keys[numNestedDimensions]]; } + /** + * Insert a value at the position specified by the given keys. + * + * This method is THREAD-SAFE despite not being synchronized, however the caller MUST + * check the return value to see if the put succeeded. This method RETURNS FALSE if + * the value could not be inserted because there already was a value present + * at the specified location. In this case the caller should do a get() to get + * the already-existing value and (potentially) update it. + * + * @param value value to insert + * @param keys keys specifying the location of the value in the tree + * @return true if the value was inserted, false if it could not be inserted because there was already + * a value at the specified position + */ public boolean put(final T value, final int... keys) { // WARNING! value comes before the keys! if ( keys.length != numDimensions ) throw new ReviewedStingException("Exactly " + numDimensions + " keys should be passed to this NestedIntegerArray but " + keys.length + " were provided");