@@ -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
@@ -458,6 +460,22 @@ int sam_hdr_nref(const sam_hdr_t *h);
458
460
459
461
/* ==== Line level methods ==== */
460
462
463
+ /*! @typedef
464
+ * @abstract Opaque type used as an iterator over header lines.
465
+ */
466
+ typedef struct sam_hrec_type_s sam_hdr_line_t ;
467
+
468
+ /// Return an iterator pointing to the first header line
469
+ HTSLIB_EXPORT
470
+ sam_hdr_line_t * sam_hdr_first_line (sam_hdr_t * h );
471
+
472
+ /// Return an iterator pointing to the next header line
473
+ /*!
474
+ * @return An iterator pointing to the next line, or NULL if there is none.
475
+ */
476
+ HTSLIB_EXPORT
477
+ sam_hdr_line_t * sam_hdr_next_line (sam_hdr_t * h , sam_hdr_line_t * line );
478
+
461
479
/// Add formatted lines to an existing header.
462
480
/*!
463
481
* @param lines Full SAM header record, eg "@SQ\tSN:foo\tLN:100", with
@@ -490,6 +508,36 @@ int sam_hdr_add_lines(sam_hdr_t *h, const char *lines, size_t len);
490
508
HTSLIB_EXPORT
491
509
int sam_hdr_add_line (sam_hdr_t * h , const char * type , ...);
492
510
511
+ /// Returns a complete line of formatted text for the line pointed to.
512
+ /*!
513
+ * @param line Iterator pointing to a header line
514
+ * @param ks kstring to which to append the result
515
+ * @return 0 on success;
516
+ * -1 if @p line does not point to a header line
517
+ * -2 on other failures
518
+ *
519
+ * Puts a complete line of formatted text for a specific line into @p ks.
520
+ * Appends the text to the existing content in @p ks, if any.
521
+ */
522
+ HTSLIB_EXPORT
523
+ int sam_hdr_format_line_append (const sam_hdr_line_t * line , kstring_t * ks );
524
+
525
+ /// Returns a complete line of formatted text for the line pointed to.
526
+ /*!
527
+ * @param line Iterator pointing to a header line
528
+ * @param ks kstring to hold the result
529
+ * @return 0 on success;
530
+ * -1 if @p line does not point to a header line
531
+ * -2 on other failures
532
+ *
533
+ * Puts a complete line of formatted text for a specific line into @p ks.
534
+ * Any existing content in @p ks will be overwritten.
535
+ */
536
+ static inline int sam_hdr_format_line (const sam_hdr_line_t * line , kstring_t * ks )
537
+ {
538
+ return sam_hdr_format_line_append (line , ks_clear (ks ));
539
+ }
540
+
493
541
/// Returns a complete line of formatted text for a given type and ID.
494
542
/*!
495
543
* @param type Type of the searched line. Eg. "SQ"
@@ -528,6 +576,14 @@ HTSLIB_EXPORT
528
576
int sam_hdr_find_line_pos (sam_hdr_t * h , const char * type ,
529
577
int pos , kstring_t * ks );
530
578
579
+ /// Remove line pointed to by iterator from a header
580
+ /*!
581
+ * @param line Iterator pointing to a header line
582
+ * @return An iterator pointing to the following line, or NULL on error FIXME or if it was the last line
583
+ */
584
+ HTSLIB_EXPORT
585
+ sam_hdr_line_t * sam_hdr_remove_line (sam_hdr_t * h , sam_hdr_line_t * line );
586
+
531
587
/// Remove a line with given type / id from a header
532
588
/*!
533
589
* @param type Type of the searched line. Eg. "SQ"
@@ -679,6 +735,21 @@ const char *sam_hdr_line_name(sam_hdr_t *bh, const char *type, int pos);
679
735
680
736
/* ==== Key:val level methods ==== */
681
737
738
+ /// Return the value associated with a key for a header line identified by iterator
739
+ /*!
740
+ * @param line Iterator pointing to a header line
741
+ * @param key Key of the searched tag. Eg. "LN"
742
+ * @param ks kstring where the value will be written
743
+ * @return 0 on success
744
+ * -1 if the requested tag does not exist
745
+ * -2 on other errors
746
+ *
747
+ * Looks for a specific key in the SAM header line pointed to by @p line and writes the
748
+ * associated value into @p ks. Any pre-existing content in @p ks will be overwritten.
749
+ */
750
+ HTSLIB_EXPORT
751
+ int sam_hdr_find_tag (const sam_hdr_line_t * line , const char * key , kstring_t * ks );
752
+
682
753
/// Return the value associated with a key for a header line identified by ID_key:ID_val
683
754
/*!
684
755
* @param type Type of the line to which the tag belongs. Eg. "SQ"
@@ -716,6 +787,15 @@ int sam_hdr_find_tag_id(sam_hdr_t *h, const char *type, const char *ID_key, cons
716
787
HTSLIB_EXPORT
717
788
int sam_hdr_find_tag_pos (sam_hdr_t * h , const char * type , int pos , const char * key , kstring_t * ks );
718
789
790
+ /// Remove the key from the line pointed to by the iterator.
791
+ /*!
792
+ * @param line Iterator pointing to a header line
793
+ * @param key Key of the targeted tag. Eg. "M5"
794
+ * @return 1 if the key was removed; 0 if it was not present; -1 on error
795
+ */
796
+ HTSLIB_EXPORT
797
+ int sam_hdr_remove_tag (sam_hdr_t * h , sam_hdr_line_t * line , const char * key );
798
+
719
799
/// Remove the key from the line identified by type, ID_key and ID_value.
720
800
/*!
721
801
* @param type Type of the line to which the tag belongs. Eg. "SQ"
0 commit comments