@@ -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,16 @@ 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
+ sam_hdr_line_itr_t * sam_hdr_line_itr_first (sam_hdr_t * h );
467
+
468
+ /// Increment iterator to point to the next header line
469
+ sam_hdr_line_itr_t * sam_hdr_line_itr_next (sam_hdr_t * h , sam_hdr_line_itr_t * iter );
470
+
459
471
/* ==== Line level methods ==== */
460
472
461
473
/// Add formatted lines to an existing header.
@@ -528,6 +540,36 @@ HTSLIB_EXPORT
528
540
int sam_hdr_find_line_pos (sam_hdr_t * h , const char * type ,
529
541
int pos , kstring_t * ks );
530
542
543
+ /// Returns a complete line of formatted text for the line pointed to.
544
+ /*!
545
+ * @param iter Iterator pointing to a header line
546
+ * @param ks kstring to hold the result
547
+ * @return 0 on success;
548
+ * -1 if @p iter does not point to a header line
549
+ * -2 on other failures
550
+ *
551
+ * Puts a complete line of formatted text for a specific line into @p ks.
552
+ * Appends the text to the existing content in @p ks, if any.
553
+ */
554
+ HTSLIB_EXPORT
555
+ int sam_hdr_find_line_iter_append (const sam_hdr_line_itr_t * iter , kstring_t * ks );
556
+
557
+ /// Returns a complete line of formatted text for the line pointed to.
558
+ /*!
559
+ * @param iter Iterator pointing to a header line
560
+ * @param ks kstring to hold the result
561
+ * @return 0 on success;
562
+ * -1 if @p iter does not point to a header line
563
+ * -2 on other failures
564
+ *
565
+ * Puts a complete line of formatted text for a specific line into @p ks.
566
+ * Any existing content in @p ks will be overwritten.
567
+ */
568
+ static inline int sam_hdr_find_line_iter (const sam_hdr_line_itr_t * iter , kstring_t * ks )
569
+ {
570
+ return sam_hdr_find_line_iter_append (iter , ks_clear (ks ));
571
+ }
572
+
531
573
/// Remove a line with given type / id from a header
532
574
/*!
533
575
* @param type Type of the searched line. Eg. "SQ"
@@ -564,6 +606,14 @@ int sam_hdr_remove_line_id(sam_hdr_t *h, const char *type, const char *ID_key, c
564
606
HTSLIB_EXPORT
565
607
int sam_hdr_remove_line_pos (sam_hdr_t * h , const char * type , int position );
566
608
609
+ /// Remove line pointed to by iterator from a header
610
+ /*!
611
+ * @param iter Iterator pointing to a header line
612
+ * @return An iterator pointing to the following line, or NULL on error
613
+ */
614
+ HTSLIB_EXPORT
615
+ sam_hdr_line_itr_t * sam_hdr_remove_line_iter (sam_hdr_t * h , sam_hdr_line_itr_t * iter );
616
+
567
617
/// Add or update tag key,value pairs in a header line.
568
618
/*!
569
619
* @param type Type of the searched line. Eg. "SQ"
@@ -716,6 +766,21 @@ int sam_hdr_find_tag_id(sam_hdr_t *h, const char *type, const char *ID_key, cons
716
766
HTSLIB_EXPORT
717
767
int sam_hdr_find_tag_pos (sam_hdr_t * h , const char * type , int pos , const char * key , kstring_t * ks );
718
768
769
+ /// Return the value associated with a key for a header line identified by iterator
770
+ /*!
771
+ * @param iter Iterator pointing to a header line
772
+ * @param key Key of the searched tag. Eg. "LN"
773
+ * @param ks kstring where the value will be written
774
+ * @return 0 on success
775
+ * -1 if the requested tag does not exist
776
+ * -2 on other errors
777
+ *
778
+ * Looks for a specific key in the SAM header line pointed to by @p iter and writes the
779
+ * associated value into @p ks. Any pre-existing content in @p ks will be overwritten.
780
+ */
781
+ HTSLIB_EXPORT
782
+ int sam_hdr_find_tag_iter (sam_hdr_line_itr_t * iter , const char * key , kstring_t * ks );
783
+
719
784
/// Remove the key from the line identified by type, ID_key and ID_value.
720
785
/*!
721
786
* @param type Type of the line to which the tag belongs. Eg. "SQ"
@@ -727,6 +792,15 @@ int sam_hdr_find_tag_pos(sam_hdr_t *h, const char *type, int pos, const char *ke
727
792
HTSLIB_EXPORT
728
793
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
794
795
+ /// Remove the key from the line pointed to by the iterator.
796
+ /*!
797
+ * @param iter Iterator pointing to a header line
798
+ * @param key Key of the targeted tag. Eg. "M5"
799
+ * @return 1 if the key was removed; 0 if it was not present; -1 on error
800
+ */
801
+ HTSLIB_EXPORT
802
+ int sam_hdr_remove_tag_iter (sam_hdr_t * h , sam_hdr_line_itr_t * iter , const char * key );
803
+
730
804
/// Get the target id for a given reference sequence name
731
805
/*!
732
806
* @param ref Reference name
0 commit comments