@@ -37,6 +37,8 @@ DEALINGS IN THE SOFTWARE. */
37
37
extern "C" {
38
38
#endif
39
39
40
+ struct sam_hrec_type_s ;
41
+
40
42
/// Highest SAM format version supported by this library
41
43
#define SAM_FORMAT_VERSION "1.6"
42
44
@@ -456,6 +458,18 @@ const char *sam_hdr_str(sam_hdr_t *h);
456
458
HTSLIB_EXPORT
457
459
int sam_hdr_nref (const sam_hdr_t * h );
458
460
461
+ /* ==== Iterator methods ==== */
462
+
463
+ typedef struct sam_hrec_type_s sam_hdr_line_itr_t ;
464
+
465
+ /// Get iterator pointing to the first header line
466
+ HTSLIB_EXPORT
467
+ sam_hdr_line_itr_t * sam_hdr_line_itr_first (sam_hdr_t * h );
468
+
469
+ /// Increment iterator to point to the next header line
470
+ HTSLIB_EXPORT
471
+ sam_hdr_line_itr_t * sam_hdr_line_itr_next (sam_hdr_t * h , sam_hdr_line_itr_t * iter );
472
+
459
473
/* ==== Line level methods ==== */
460
474
461
475
/// Add formatted lines to an existing header.
@@ -528,6 +542,36 @@ HTSLIB_EXPORT
528
542
int sam_hdr_find_line_pos (sam_hdr_t * h , const char * type ,
529
543
int pos , kstring_t * ks );
530
544
545
+ /// Returns a complete line of formatted text for the line pointed to.
546
+ /*!
547
+ * @param iter Iterator pointing to a header line
548
+ * @param ks kstring to hold the result
549
+ * @return 0 on success;
550
+ * -1 if @p iter does not point to a header line
551
+ * -2 on other failures
552
+ *
553
+ * Puts a complete line of formatted text for a specific line into @p ks.
554
+ * Appends the text to the existing content in @p ks, if any.
555
+ */
556
+ HTSLIB_EXPORT
557
+ int sam_hdr_find_line_iter_append (const sam_hdr_line_itr_t * iter , kstring_t * ks );
558
+
559
+ /// Returns a complete line of formatted text for the line pointed to.
560
+ /*!
561
+ * @param iter Iterator pointing to a header line
562
+ * @param ks kstring to hold the result
563
+ * @return 0 on success;
564
+ * -1 if @p iter does not point to a header line
565
+ * -2 on other failures
566
+ *
567
+ * Puts a complete line of formatted text for a specific line into @p ks.
568
+ * Any existing content in @p ks will be overwritten.
569
+ */
570
+ static inline int sam_hdr_find_line_iter (const sam_hdr_line_itr_t * iter , kstring_t * ks )
571
+ {
572
+ return sam_hdr_find_line_iter_append (iter , ks_clear (ks ));
573
+ }
574
+
531
575
/// Remove a line with given type / id from a header
532
576
/*!
533
577
* @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
564
608
HTSLIB_EXPORT
565
609
int sam_hdr_remove_line_pos (sam_hdr_t * h , const char * type , int position );
566
610
611
+ /// Remove line pointed to by iterator from a header
612
+ /*!
613
+ * @param iter Iterator pointing to a header line
614
+ * @return An iterator pointing to the following line, or NULL on error
615
+ */
616
+ HTSLIB_EXPORT
617
+ sam_hdr_line_itr_t * sam_hdr_remove_line_iter (sam_hdr_t * h , sam_hdr_line_itr_t * iter );
618
+
567
619
/// Add or update tag key,value pairs in a header line.
568
620
/*!
569
621
* @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
716
768
HTSLIB_EXPORT
717
769
int sam_hdr_find_tag_pos (sam_hdr_t * h , const char * type , int pos , const char * key , kstring_t * ks );
718
770
771
+ /// Return the value associated with a key for a header line identified by iterator
772
+ /*!
773
+ * @param iter Iterator pointing to a header line
774
+ * @param key Key of the searched tag. Eg. "LN"
775
+ * @param ks kstring where the value will be written
776
+ * @return 0 on success
777
+ * -1 if the requested tag does not exist
778
+ * -2 on other errors
779
+ *
780
+ * Looks for a specific key in the SAM header line pointed to by @p iter and writes the
781
+ * associated value into @p ks. Any pre-existing content in @p ks will be overwritten.
782
+ */
783
+ HTSLIB_EXPORT
784
+ int sam_hdr_find_tag_iter (sam_hdr_line_itr_t * iter , const char * key , kstring_t * ks );
785
+
719
786
/// Remove the key from the line identified by type, ID_key and ID_value.
720
787
/*!
721
788
* @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
727
794
HTSLIB_EXPORT
728
795
int sam_hdr_remove_tag_id (sam_hdr_t * h , const char * type , const char * ID_key , const char * ID_value , const char * key );
729
796
797
+ /// Remove the key from the line pointed to by the iterator.
798
+ /*!
799
+ * @param iter Iterator pointing to a header line
800
+ * @param key Key of the targeted tag. Eg. "M5"
801
+ * @return 1 if the key was removed; 0 if it was not present; -1 on error
802
+ */
803
+ HTSLIB_EXPORT
804
+ int sam_hdr_remove_tag_iter (sam_hdr_t * h , sam_hdr_line_itr_t * iter , const char * key );
805
+
730
806
/// Get the target id for a given reference sequence name
731
807
/*!
732
808
* @param ref Reference name
0 commit comments