Add SAM header iterator methods [DRAFT]

Author: jmarshall

header.c

@@ -1271,6 +1271,22 @@ int sam_hdr_rebuild(sam_hdr_t *bh) {
     return 0;
 }
 
+/*
+ * Iterators
+ */
+
+sam_hdr_line_itr_t *sam_hdr_line_itr_first(sam_hdr_t *bh) {
+    if (!bh->hrecs) {
+        if (sam_hdr_fill_hrecs(bh) != 0) return NULL;
+    }
+    return bh->hrecs->first_line;
+}
+
+sam_hdr_line_itr_t *sam_hdr_line_itr_next(sam_hdr_t *bh, sam_hdr_line_itr_t *iter) {
+    iter = iter->global_next;
+    return (iter != bh->hrecs->first_line)? iter : NULL;
+}
+
 /*
  * Appends a formatted line to an existing SAM header.
  * Line is a full SAM header record, eg "@SQ\tSN:foo\tLN:100", with
@@ -1399,6 +1415,15 @@ int sam_hdr_find_line_pos(sam_hdr_t *bh, const char *type,
     return 0;
 }
 
+int sam_hdr_find_line_iter_append(const sam_hdr_line_itr_t *iter, kstring_t *ks) {
+    if (!iter) return -1;
+
+    if (build_header_line(iter, ks) < 0) return -2;
+    return 0;
+}
+
+/* ==== Key:val level methods ==== */
+
 /*
  * Remove a line from the header by specifying a tag:value that uniquely
  * identifies a line, i.e. the @SQ line containing "SN:ref1".
@@ -1481,6 +1506,26 @@ int sam_hdr_remove_line_pos(sam_hdr_t *bh, const char *type, int position) {
     return ret;
 }
 
+/*
+ * Remove a line from the header via an iterator.
+ */
+sam_hdr_line_itr_t *sam_hdr_remove_line_iter(sam_hdr_t *bh, sam_hdr_line_itr_t *iter) {
+    if (!bh || !iter) return NULL;
+
+    if (iter->type == TYPEKEY("PG")) {
+        hts_log_warning("Removing PG lines is not supported!");
+        return NULL;
+    }
+
+    sam_hdr_line_itr_t *next = sam_hdr_line_itr_next(bh, iter);
+    char type[2] = { iter->type >> 8, iter->type & 0xff };
+    if (sam_hrecs_remove_line(bh->hrecs, type, iter) < 0) return NULL;
+
+    if (bh->hrecs->refs_changed >= 0 && rebuild_target_arrays(bh) != 0) return NULL;
+    if (bh->hrecs->dirty) redact_header_text(bh);
+    return next;
+}
+
 /*
  * Check if sam_hdr_update_line() is being used to change the name of
  * a record, and if the new name is going to clash with an existing one.
@@ -1920,6 +1965,19 @@ int sam_hdr_find_tag_pos(sam_hdr_t *bh,
     return 0;
 }
 
+int sam_hdr_find_tag_iter(sam_hdr_line_itr_t *iter,
+                          const char *key,
+                          kstring_t *ks) {
+    if (!iter || !key) return -2;
+
+    sam_hrec_tag_t *tag = sam_hrecs_find_key(iter, key, NULL);
+    if (!tag || tag->len < 3) return -1;
+
+    ks_clear(ks);
+    if (kputsn(&tag->str[3], tag->len-3, ks) < 0) return -2;
+    return 0;
+}
+
 int sam_hdr_remove_tag_id(sam_hdr_t *bh,
         const char *type,
         const char *ID_key,
@@ -1946,6 +2004,16 @@ int sam_hdr_remove_tag_id(sam_hdr_t *bh,
     return ret;
 }
 
+int sam_hdr_remove_tag_iter(sam_hdr_t *bh,
+                            sam_hdr_line_itr_t *iter,
+                            const char *key) {
+    if (!bh || !iter || !key) return -1;
+
+    int ret = sam_hrecs_remove_key(bh->hrecs, iter, key);
+    if (ret == 0 && bh->hrecs->dirty) redact_header_text(bh);
+    return ret;
+}
+
 /*
  * Reconstructs a kstring from the header hash table.
  * Returns 0 on success

htslib/sam.h

@@ -37,6 +37,8 @@ DEALINGS IN THE SOFTWARE.  */
 extern "C" {
 #endif
 
+struct sam_hrec_type_s;
+
 /// Highest SAM format version supported by this library
 #define SAM_FORMAT_VERSION "1.6"
 
@@ -456,6 +458,18 @@ const char *sam_hdr_str(sam_hdr_t *h);
 HTSLIB_EXPORT
 int sam_hdr_nref(const sam_hdr_t *h);
 
+/* ==== Iterator methods ==== */
+
+typedef struct sam_hrec_type_s sam_hdr_line_itr_t;
+
+/// Get iterator pointing to the first header line
+HTSLIB_EXPORT
+sam_hdr_line_itr_t *sam_hdr_line_itr_first(sam_hdr_t *h);
+
+/// Increment iterator to point to the next header line
+HTSLIB_EXPORT
+sam_hdr_line_itr_t *sam_hdr_line_itr_next(sam_hdr_t *h, sam_hdr_line_itr_t *iter);
+
 /* ==== Line level methods ==== */
 
 /// Add formatted lines to an existing header.
@@ -528,6 +542,36 @@ HTSLIB_EXPORT
 int sam_hdr_find_line_pos(sam_hdr_t *h, const char *type,
                           int pos, kstring_t *ks);
 
+/// Returns a complete line of formatted text for the line pointed to.
+/*!
+ * @param iter      Iterator pointing to a header line
+ * @param ks        kstring to hold the result
+ * @return          0 on success;
+ *                 -1 if @p iter does not point to a header line
+ *                 -2 on other failures
+ *
+ * Puts a complete line of formatted text for a specific line into @p ks.
+ * Appends the text to the existing content in @p ks, if any.
+ */
+HTSLIB_EXPORT
+int sam_hdr_find_line_iter_append(const sam_hdr_line_itr_t *iter, kstring_t *ks);
+
+/// Returns a complete line of formatted text for the line pointed to.
+/*!
+ * @param iter      Iterator pointing to a header line
+ * @param ks        kstring to hold the result
+ * @return          0 on success;
+ *                 -1 if @p iter does not point to a header line
+ *                 -2 on other failures
+ *
+ * Puts a complete line of formatted text for a specific line into @p ks.
+ * Any existing content in @p ks will be overwritten.
+ */
+static inline int sam_hdr_find_line_iter(const sam_hdr_line_itr_t *iter, kstring_t *ks)
+{
+    return sam_hdr_find_line_iter_append(iter, ks_clear(ks));
+}
+
 /// Remove a line with given type / id from a header
 /*!
  * @param type      Type of the searched line. Eg. "SQ"
@@ -564,6 +608,14 @@ int sam_hdr_remove_line_id(sam_hdr_t *h, const char *type, const char *ID_key, c
 HTSLIB_EXPORT
 int sam_hdr_remove_line_pos(sam_hdr_t *h, const char *type, int position);
 
+/// Remove line pointed to by iterator from a header
+/*!
+ * @param iter     Iterator pointing to a header line
+ * @return         An iterator pointing to the following line, or NULL on error
+ */
+HTSLIB_EXPORT
+sam_hdr_line_itr_t *sam_hdr_remove_line_iter(sam_hdr_t *h, sam_hdr_line_itr_t *iter);
+
 /// Add or update tag key,value pairs in a header line.
 /*!
  * @param type      Type of the searched line. Eg. "SQ"
@@ -716,6 +768,21 @@ int sam_hdr_find_tag_id(sam_hdr_t *h, const char *type, const char *ID_key, cons
 HTSLIB_EXPORT
 int sam_hdr_find_tag_pos(sam_hdr_t *h, const char *type, int pos, const char *key, kstring_t *ks);
 
+/// Return the value associated with a key for a header line identified by iterator
+/*!
+ * @param iter      Iterator pointing to a header line
+ * @param key       Key of the searched tag. Eg. "LN"
+ * @param ks        kstring where the value will be written
+ * @return          0 on success
+ *                 -1 if the requested tag does not exist
+ *                 -2 on other errors
+ *
+ * Looks for a specific key in the SAM header line pointed to by @p iter and writes the
+ * associated value into @p ks.  Any pre-existing content in @p ks will be overwritten.
+ */
+HTSLIB_EXPORT
+int sam_hdr_find_tag_iter(sam_hdr_line_itr_t *iter, const char *key, kstring_t *ks);
+
 /// Remove the key from the line identified by type, ID_key and ID_value.
 /*!
  * @param type      Type of the line to which the tag belongs. Eg. "SQ"
@@ -727,6 +794,15 @@ int sam_hdr_find_tag_pos(sam_hdr_t *h, const char *type, int pos, const char *ke
 HTSLIB_EXPORT
 int sam_hdr_remove_tag_id(sam_hdr_t *h, const char *type, const char *ID_key, const char *ID_value, const char *key);
 
+/// Remove the key from the line pointed to by the iterator.
+/*!
+ * @param iter      Iterator pointing to a header line
+ * @param key       Key of the targeted tag. Eg. "M5"
+ * @return          1 if the key was removed; 0 if it was not present; -1 on error
+ */
+HTSLIB_EXPORT
+int sam_hdr_remove_tag_iter(sam_hdr_t *h, sam_hdr_line_itr_t *iter, const char *key);
+
 /// Get the target id for a given reference sequence name
 /*!
  * @param ref  Reference name