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: if modifier 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(int16_t value)

Creates a Tag from 16-bit integer.

Tag(uint16_t value)

Creates a Tag from 16-bit unsigned integer.

Tag(int32_t value)

Creates a Tag from 32-bit signed integer.

Tag(uint32_t value)

Creates a Tag from 32-bit unsigned integer.

Tag(float value)

Creates a Tag from floating-point value.

Tag(const std::string &value)

Creates a Tag from string data.

Tag(const std::string &value, const TagModifier mod)

Creates a Tag from string data, adding modifier.

Exceptions
  • runtime_error: if modifier is not valid for string data

Tag(const std::vector<int8_t> &value)

Creates a Tag from a vector of 8-bit integers.

Tag(const std::vector<uint8_t> &value)

Creates a Tag from a vector of 8-bit unsigned integers.

Tag(const std::vector<int16_t> &value)

Creates a Tag from a vector of 16-bit integers.

Tag(const std::vector<uint16_t> &value)

Creates a Tag from a vector of 16-bit unsigned integers.

Tag(const std::vector<int32_t> &value)

Constructs a Tag from a vector of 32-bit integers.

Tag(const std::vector<uint32_t> &value)

Creates a Tag from a vector of 32-bit unsigned integers.

Tag(const std::vector<float> &value)

Creates a Tag from a vector of floating-point values.

Tag(const Tag &other)
Tag(Tag &&other)
~Tag()
Tag &operator=(boost::blank value)
Tag &operator=(int8_t value)
Tag &operator=(uint8_t value)
Tag &operator=(int16_t value)
Tag &operator=(uint16_t value)
Tag &operator=(int32_t value)
Tag &operator=(uint32_t value)
Tag &operator=(float value)
Tag &operator=(const std::string &value)
Tag &operator=(const std::vector<int8_t> &value)
Tag &operator=(const std::vector<uint8_t> &value)
Tag &operator=(const std::vector<int16_t> &value)
Tag &operator=(const std::vector<uint16_t> &value)
Tag &operator=(const std::vector<int32_t> &value)
Tag &operator=(const std::vector<uint32_t> &value)
Tag &operator=(const std::vector<float> &value)
Tag &operator=(const Tag &other)
Tag &operator=(Tag &&other)
bool operator==(const Tag &other) const
bool operator!=(const Tag &other) const

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