Tag¶
#include <pbbam/Tag.h>
-
enum
PacBio::BAM::
TagDataType
¶ This enum is used to describe the exact (C++) data type held by a Tag.
Values:
-
INVALID
= 0¶ boost::blank
-
INT8
¶ int8_t
-
UINT8
¶ uint8_t
-
INT16
¶ int16_t
-
UINT16
¶ uint16_t
-
INT32
= 5¶ int32_t
-
UINT32
¶ uint32_t
-
FLOAT
¶ float
-
STRING
¶ std::string
-
INT8_ARRAY
¶ std::vector<int8_t>
-
UINT8_ARRAY
= 10¶ std::vector<uint8_t>
-
INT16_ARRAY
¶ std::vector<int16_t>
-
UINT16_ARRAY
¶ std::vector<uint16_t>
-
INT32_ARRAY
¶ std::vector<int32_t>
-
UINT32_ARRAY
¶ std::vector<uint32_t>
-
FLOAT_ARRAY
= 15¶ std::vector<float>
-
-
enum
PacBio::BAM::
TagModifier
¶ This enum provides additional instructions on interpreting the tag’s value.
Some C++ data types (e.g. std::string) may represent more than one BAM tag type (‘H’ vs ‘Z’). Thus a TagModifier may be used to indicate how to properly distinguish between these shared data types.
Values:
-
NONE
= 0¶ This value indicates that the tag has no modifiers set.
-
ASCII_CHAR
¶ This modifier marks an integer as ASCII.
SAM/BAM has the concept of an ASCII character that is distinct from an 8-bit integer. However, there is no such pure separation in C++ - as int8_t/uint8_t are likely implemented as typedefs around char/unsigned char. Thus this modifier can be used to indicate a tag’s value should be interpreted as a printable, ASCII character.
-
HEX_STRING
¶ This modifier marks std::string data as “hex string”, rather than a regular string.
SAM/BAM has a distinction between regular strings and “Hex format” strings. However, they are both manipulated in C++ via std::string. Thus this modifier can be used to indicate that a tag’s string data should be interpreted as “Hex format” rather than a regular, literal string.
-
-
class
PacBio::BAM::
Tag
¶ The Tag class represents a SAM/BAM record tag value.
SAM/BAM tags may store values from a variety of types: varying fixed-width integers, strings, arrays of data, etc.
The Tag class allow tags to be handled in a generic fashion, while maintaining a high level of type-safety. Only those types recognized by the SAM/BAM format are allowed, and extracting the value from a tag is subject to allowed conversion rules, as well.
Constructors & Related Methods
-
Tag
()¶ Creates an empty, null tag.
-
Tag
(int8_t value)¶ Creates a Tag from a signed 8-bit integer or character.
Without a TagModifier, the resulting Tag will be annotated as containing an 8-bit integer, whether the input
value
was an integer or a char. For ASCII tags, use one of these methods:// One-step construction // // This is useful in situations that require a const Tag. // const auto t = Tag('A', TagModifier::ASCII_CHAR); // or two-step construction auto t = Tag('A'); t.Modifier(TagModifier::ASCII_CHAR);
-
Tag
(int8_t value, const TagModifier mod)¶ Creates a Tag from a signed 8-bit integer or character, applying the provided modifier.
This method allows direct construction of an ASCII character, rather than an 8-bit integer (e.g. Tag(‘A’, TagModifier::ASCII_CHAR) ).
- Exceptions
runtime_error
: ifmodifier
is not valid for int8_t data
-
Tag
(uint8_t value)¶ Creates a Tag from an unsigned 8-bit integer or character.
Without a TagModifier, the resulting Tag will be annotated as containing an 8-bit unsigned integer, whether the input
value
was an integer or a char. For ASCII tags, use one of these methods:// One-step construction // // This is useful in situations that require a const Tag. // const auto t = Tag('A', TagModifier::ASCII_CHAR); // or two-step construction auto t = Tag('A'); t.Modifier(TagModifier::ASCII_CHAR);
-
Tag
(const std::string &value, const TagModifier mod)¶ Creates a Tag from string data, adding modifier.
- Exceptions
runtime_error
: ifmodifier
is not valid for string data
-
~Tag
()¶
Data Conversion & Validation
-
char
ToAscii
() const¶ Converts the tag value to an ASCII character.
Tag must hold an integral type, within the valid ASCII range [33-127].
- Return
- ASCII character value
- Exceptions
std::runtime_error
: if not ASCII-compatible
-
int8_t
ToInt8
() const¶ - Return
- tag data as signed 8-bit (casting if needed)
- Exceptions
std::runtime_error
: if not integral data, or out of valid range
-
uint8_t
ToUInt8
() const¶ - Return
- tag data as unsigned 8-bit (casting if needed)
- Exceptions
std::runtime_error
: if not integral data, or out of valid range
-
int16_t
ToInt16
() const¶ - Return
- tag data as signed 16-bit (casting if needed)
- Exceptions
std::runtime_error
: if not integral data, or out of valid range
-
uint16_t
ToUInt16
() const¶ - Return
- tag data as unsigned 16-bit (casting if needed)
- Exceptions
std::runtime_error
: if not integral data, or out of valid range
-
int32_t
ToInt32
() const¶ - Return
- tag data as signed 32-bit (casting if needed)
- Exceptions
std::runtime_error
: if not integral data, or out of valid range
-
uint32_t
ToUInt32
() const¶ - Return
- tag data as unsigned 32-bit (casting if needed)
- Exceptions
std::runtime_error
: if not integral data, or out of valid range
-
float
ToFloat
() const¶ - Return
- tag data as float
- Exceptions
std::runtime_error
: if tag does not contain a value of explicit type: float
-
std::string
ToString
() const¶ - Return
- tag data as std::string
- Exceptions
std::runtime_error
: if tag does not contain a value of explicit type: std::string
-
std::vector<int8_t>
ToInt8Array
() const¶ - Return
- tag data as std::vector<int8_t>
- Exceptions
std::runtime_error
: if tag does not contain a value of explicit type: std::vector<int8_t>
-
std::vector<uint8_t>
ToUInt8Array
() const¶ - Return
- tag data as std::vector<uint8_t>
- Exceptions
std::runtime_error
: if tag does not contain a value of explicit type: std::vector<uint8_t>
-
std::vector<int16_t>
ToInt16Array
() const¶ - Return
- tag data as std::vector<int16_t>
- Exceptions
std::runtime_error
: if tag does not contain a value of explicit type: std::vector<int16_t>
-
std::vector<uint16_t>
ToUInt16Array
() const¶ - Return
- tag data as std::vector<uint16_t>
- Exceptions
std::runtime_error
: if tag does not contain a value of explicit type: std::vector<uint16_t>
-
std::vector<int32_t>
ToInt32Array
() const¶ - Return
- tag data as std::vector<int32_t>
- Exceptions
std::runtime_error
: if tag does not contain a value of explicit type: std::vector<int32_t>
-
std::vector<uint32_t>
ToUInt32Array
() const¶ - Return
- tag data as std::vector<uint32_t>
- Exceptions
std::runtime_error
: if tag does not contain a value of explicit type: std::vector<uint32_t>
-
std::vector<float>
ToFloatArray
() const¶ - Return
- tag data as std::vector<float>
- Exceptions
std::runtime_error
: if tag does not contain a value of explicit type: std::vector<float>
-
bool
IsNull
() const¶ - Return
- true if tag is null (e.g. default-constructed)
-
bool
IsInt8
() const¶ - Return
- true if tag contains a value of type: int8_t
-
bool
IsUInt8
() const¶ - Return
- true if tag contains a value of type: uint8_t
-
bool
IsInt16
() const¶ - Return
- true if tag contains a value of type: int16_t
-
bool
IsUInt16
() const¶ - Return
- true if tag contains a value of type: uint16_t
-
bool
IsInt32
() const¶ - Return
- true if tag contains a value of type: int32_t
-
bool
IsUInt32
() const¶ - Return
- true if tag contains a value of type: uint32_t
-
bool
IsFloat
() const¶ - Return
- true if tag contains a value of type: float
-
bool
IsString
() const¶ - Return
- true if tag contains a value of type: std::string
-
bool
IsHexString
() const¶ - Return
- true if tag contains a value of type: std::string AND has a TagModifier of TagModifier::HEX_STRING
-
bool
IsInt8Array
() const¶ - Return
- true if tag contains a value of type: std::vector<int8_t>
-
bool
IsUInt8Array
() const¶ - Return
- true if tag contains a value of type: std::vector<uint8_t>
-
bool
IsInt16Array
() const¶ - Return
- true if tag contains a value of type: std::vector<int16_t>
-
bool
IsUInt16Array
() const¶ - Return
- true if tag contains a value of type: std::vector<uint16_t>
-
bool
IsInt32Array
() const¶ - Return
- true if tag contains a value of type: std::vector<int32_t>
-
bool
IsUInt32Array
() const¶ - Return
- true if tag contains a value of type: std::vector<uint32_t>
-
bool
IsFloatArray
() const¶ - Return
- true if tag contains a value of type: std::vector<float>
-
bool
IsSignedInt
() const¶ - Return
- true if tag contains a value with any signed integer type
-
bool
IsUnsignedInt
() const¶ - Return
- true if tag contains a value with any unsigned integer type
-
bool
IsIntegral
() const¶ - Return
- true if tag contains a value with any integer type
-
bool
IsNumeric
() const¶ - Return
- true if tag contains a value with any integer or float type
-
bool
IsSignedArray
() const¶ - Return
- true if tag contains a vector containing signed integers
-
bool
IsUnsignedArray
() const¶ - Return
- true if tag contains a vector containing unsigned integers
-
bool
IsIntegralArray
() const¶ - Return
- true if tag contains a vector containing integers
-
bool
IsArray
() const¶ - Return
- true if tag contains a vector (integers or floats)
Type & Modifier Attributes
-
TagDataType
Type
() const¶ - Return
- enum value for current tag data
-
std::string
Typename
() const¶ - Return
- printable type name for current tag data
-
bool
HasModifier
(const TagModifier m) const¶ - Return
- true if tag data modifier
m
is set
-
TagModifier
Modifier
() const¶ - Return
- current tag data modifier
-
Tag &
Modifier
(const TagModifier m)¶ Sets tag data modifier.
- Return
- reference to this tag
- Parameters
m
: new modifier value
-