Deprecating SAMTagUtil (#1227)

* Deprecating SAMTagUtil and moving methods to SAMTag instead.  This provides a single uniform place to deal with tags which should reduce confusion.
*  reverted some unreleased changes to SAMTagUtil that caused binary compatibility breaks

src/main/java/htsjdk/samtools/SAMBinaryTagAndUnsignedArrayValue.java

@@ -35,7 +35,7 @@ public SAMBinaryTagAndUnsignedArrayValue(final short tag, final Object value) {
         if (!value.getClass().isArray() || value instanceof float[]) {
             throw new IllegalArgumentException("Attribute type " + value.getClass() +
                     " cannot be encoded as an unsigned array. Tag: " +
-                    SAMTagUtil.makeStringTag(tag));
+                    SAMTag.makeStringTag(tag));
         }
     }
 

src/main/java/htsjdk/samtools/SAMBinaryTagAndValue.java

@@ -59,7 +59,7 @@ public SAMBinaryTagAndValue(final short tag, final Object value) {
         }
         if (!isAllowedAttributeValue(value)) {
             throw new IllegalArgumentException("Attribute type " + value.getClass() + " not supported. Tag: " +
-                    SAMTagUtil.makeStringTag(tag));
+                    SAMTag.makeStringTag(tag));
         }
         this.tag = tag;
         this.value = value;

src/main/java/htsjdk/samtools/SAMRecord.java

@@ -1163,7 +1163,7 @@ public boolean hasAttribute(final String tag) {
      * @return Appropriately typed tag value, or null if the requested tag is not present.
      */
     public Object getAttribute(final String tag) {
-        return getAttribute(SAMTagUtil.makeBinaryTag(tag));
+        return getAttribute(SAMTag.makeBinaryTag(tag));
     }
 
     /**
@@ -1197,7 +1197,7 @@ public Integer getIntegerAttribute(final String tag) {
      * @throws {@link htsjdk.samtools.SAMException} if the value is out of range for a 32-bit unsigned value, or not a Number
      */
     public Long getUnsignedIntegerAttribute(final String tag) throws SAMException {
-        return getUnsignedIntegerAttribute(SAMTagUtil.makeBinaryTag(tag));
+        return getUnsignedIntegerAttribute(SAMTag.makeBinaryTag(tag));
     }
 
     /**
@@ -1220,11 +1220,11 @@ public Long getUnsignedIntegerAttribute(final short tag) throws SAMException {
                 return lValue;
             } else {
                 throw new SAMException("Unsigned integer value of tag " +
-                        SAMTagUtil.makeStringTag(tag) + " is out of bounds for a 32-bit unsigned integer: " + lValue);
+                        SAMTag.makeStringTag(tag) + " is out of bounds for a 32-bit unsigned integer: " + lValue);
             }
         } else {
             throw new SAMException("Unexpected attribute value data type " + value.getClass() + " for tag " +
-                    SAMTagUtil.makeStringTag(tag));
+                    SAMTag.makeStringTag(tag));
         }
     }
 
@@ -1375,7 +1375,7 @@ public float[] getFloatArrayAttribute(final String tag) {
      * @throws SAMException if the tag is not present.
      */
     public boolean isUnsignedArrayAttribute(final String tag) {
-        final SAMBinaryTagAndValue tmp = this.mAttributes.find(SAMTagUtil.makeBinaryTag(tag));
+        final SAMBinaryTagAndValue tmp = this.mAttributes.find(SAMTag.makeBinaryTag(tag));
         if (tmp != null) return tmp.isUnsignedArray();
         throw new SAMException("Tag " + tag + " is not present in this SAMRecord");
     }
@@ -1420,7 +1420,7 @@ public Object getAttribute(final short tag) {
      * String values are not validated to ensure that they conform to SAM spec.
      */
     public void setAttribute(final String tag, final Object value) {
-        setAttribute(SAMTagUtil.makeBinaryTag(tag), value);
+        setAttribute(SAMTag.makeBinaryTag(tag), value);
     }
 
     /**
@@ -1436,7 +1436,7 @@ public void setUnsignedArrayAttribute(final String tag, final Object value) {
         if (Array.getLength(value) == 0) {
             throw new IllegalArgumentException("Empty array passed to setUnsignedArrayAttribute for tag " + tag);
         }
-        setAttribute(SAMTagUtil.makeBinaryTag(tag), value, true);
+        setAttribute(SAMTag.makeBinaryTag(tag), value, true);
     }
 
     /**
@@ -1557,7 +1557,7 @@ public List<SAMTagAndValue> getAttributes() {
         SAMBinaryTagAndValue binaryAttributes = getBinaryAttributes();
         final List<SAMTagAndValue> ret = new ArrayList<>();
         while (binaryAttributes != null) {
-            ret.add(new SAMTagAndValue(SAMTagUtil.makeStringTag(binaryAttributes.tag),
+            ret.add(new SAMTagAndValue(SAMTag.makeStringTag(binaryAttributes.tag),
                                        binaryAttributes.value));
             binaryAttributes = binaryAttributes.getNext();
         }
@@ -1771,7 +1771,7 @@ private void addField(final StringBuilder buffer, final String field) {
     }
 
     private static String formatTagValue(final short tag, final Object value) {
-        final String tagString = SAMTagUtil.makeStringTag(tag);
+        final String tagString = SAMTag.makeStringTag(tag);
         if (value == null || value instanceof String) {
             return tagString + ":Z:" + value;
         } else if (value instanceof Integer || value instanceof Long ||

src/main/java/htsjdk/samtools/SAMTag.java

@@ -23,6 +23,8 @@
  */
 package htsjdk.samtools;
 
+import htsjdk.samtools.util.StringUtil;
+
 /**
  * The standard tags for a SAM record that are defined in the SAM spec.
  */
@@ -105,24 +107,46 @@ public enum SAMTag {
     U2,
     UQ;
 
-    private final short shortValue = SAMTag.makeBinaryTag(this.name());;
+    // Cache of already-converted tags.  Should speed up SAM text generation.
+    // Not synchronized because race condition is not a problem.
+    private static final String[] stringTags = new String[Short.MAX_VALUE];
+
+    private final short shortValue = SAMTag.makeBinaryTag(this.name());
 
     /**
      * Convert from String representation of tag name to short representation.
      *
      * @param tag 2-character String representation of a tag name.
      * @return Tag name packed as 2 ASCII bytes in a short.
      */
-    static short makeBinaryTag(String tag) {
+    public static short makeBinaryTag(String tag) {
         if (tag.length() != 2) {
             throw new IllegalArgumentException("String tag does not have length() == 2: " + tag);
         }
         return (short)(tag.charAt(1) << 8 | tag.charAt(0));
     }
 
+    /**
+     * Convert from short representation of tag name to String representation.
+     *
+     * @param tag Tag name packed as 2 ASCII bytes in a short.
+     * @return 2-character String representation of a tag name.
+     */
+    public static String makeStringTag(final short tag) {
+        String ret = stringTags[tag];
+        if (ret == null) {
+            final byte[] stringConversionBuf = new byte[2];
+            stringConversionBuf[0] = (byte)(tag & 0xff);
+            stringConversionBuf[1] = (byte)((tag >> 8) & 0xff);
+            ret = StringUtil.bytesToString(stringConversionBuf);
+            stringTags[tag] = ret;
+        }
+        return ret;
+    }
+
     /**
      * Get the binary representation of this tag name.
-     * @see SAMTagUtil#makeBinaryTag(String)
+     * @see #makeBinaryTag(String)
      *
      * @return the binary representation of this tag name
      */