## hb-common hb-common — Common data types |

## Functions

hb_tag_t | hb_tag_from_string ()
void | hb_tag_to_string ()
hb_direction_t | hb_direction_from_string ()
const char * | hb_direction_to_string ()
hb_script_t | hb_script_from_iso15924_tag ()
hb_script_t | hb_script_from_string ()
hb_tag_t | hb_script_to_iso15924_tag ()
hb_direction_t | hb_script_get_horizontal_direction ()
hb_language_t | hb_language_from_string ()
const char * | hb_language_to_string ()
hb_language_t | hb_language_get_default ()
hb_bool_t | hb_feature_from_string ()
void | hb_feature_to_string ()
hb_bool_t | hb_variation_from_string ()
void | hb_variation_to_string ()
void | (*hb_destroy_func_t) ()
#define | HB_TAG()
#define | HB_UNTAG()
#define | HB_DIRECTION_REVERSE()
#define | HB_DIRECTION_IS_BACKWARD()
#define | HB_DIRECTION_IS_FORWARD()
#define | HB_DIRECTION_IS_HORIZONTAL()
#define | HB_DIRECTION_IS_VALID()
#define | HB_DIRECTION_IS_VERTICAL()

## Types and Values

typedef | hb_bool_t
typedef | hb_codepoint_t
enum | hb_direction_t
typedef | hb_language_t
| hb_feature_t
| hb_variation_t
typedef | hb_mask_t
typedef | hb_position_t
typedef | hb_tag_t
enum | hb_script_t
| hb_user_data_key_t
| hb_var_int_t
#define | HB_TAG_NONE
#define | HB_TAG_MAX
#define | HB_TAG_MAX_SIGNED
#define | HB_LANGUAGE_INVALID
#define | HB_FEATURE_GLOBAL_END
#define | HB_FEATURE_GLOBAL_START

## Includes

    #include <hb.h>

## Description

Common data types used across HarfBuzz are defined here.

## Functions

### hb_tag_from_string ()

    hb_tag_t
    hb_tag_from_string (const char *str,
                        int len);

Converts a string into an hb_tag_t. Valid tags are four characters. Shorter input strings will be padded with spaces. Longer input strings will be truncated.

#### Parameters

str | String to convert. | [array length=len][element-type uint8_t]
len | Length of `str` , or -1 if it is `NULL`-terminated |

#### Returns

The hb_tag_t corresponding to `str`

Since: 0.9.2

### hb_tag_to_string ()

    void
    hb_tag_to_string (hb_tag_t tag,
                      char *buf);

Converts an hb_tag_t to a string and returns it in `buf` . Strings will be four characters long.

#### Parameters

tag | hb_tag_t to convert |
buf | Converted string. | [out caller-allocates][array fixed-size=4][element-type uint8_t]

Since: 0.9.5

### hb_direction_from_string ()

    hb_direction_t
    hb_direction_from_string (const char *str,
                              int len);

Converts a string to an hb_direction_t.

Matching is loose and applies only to the first letter. For examples, "LTR" and "left-to-right" will both return HB_DIRECTION_LTR.

Unmatched strings will return HB_DIRECTION_INVALID.

#### Parameters

str | String to convert. | [array length=len][element-type uint8_t]
len | Length of `str` , or -1 if it is `NULL`-terminated |

#### Returns

The hb_direction_t matching `str`

Since: 0.9.2

### hb_direction_to_string ()

    const char *
    hb_direction_to_string (hb_direction_t direction);

Converts an hb_direction_t to a string.

#### Parameters

direction | The hb_direction_t to convert |

#### Returns

The string corresponding to `direction` .

[transfer none]

Since: 0.9.2

### hb_script_from_iso15924_tag ()

    hb_script_t
    hb_script_from_iso15924_tag (hb_tag_t tag);

Converts an ISO 15924 script tag to a corresponding hb_script_t.

#### Parameters

tag | an hb_tag_t representing an ISO 15924 tag. |

#### Returns

An hb_script_t corresponding to the ISO 15924 tag.

Since: 0.9.2

### hb_script_from_string ()

    hb_script_t
    hb_script_from_string (const char *str,
                           int len);

Converts a string `str` representing an ISO 15924 script tag to a corresponding hb_script_t. Shorthand for `hb_tag_from_string()` then `hb_script_from_iso15924_tag()`.

#### Parameters

str | a string representing an ISO 15924 tag. | [array length=len][element-type uint8_t]
len | length of the `str` , or -1 if it is `NULL`-terminated. |

#### Returns

An hb_script_t corresponding to the ISO 15924 tag.

Since: 0.9.2

### hb_script_to_iso15924_tag ()

    hb_tag_t
    hb_script_to_iso15924_tag (hb_script_t script);

Converts an hb_script_t to a corresponding ISO 15924 script tag.

#### Parameters

script | an hb_script_t to convert. |

#### Returns

An hb_tag_t representing an ISO 15924 script tag.

Since: 0.9.2

### hb_script_get_horizontal_direction ()

    hb_direction_t
    hb_script_get_horizontal_direction (hb_script_t script);

Fetches the hb_direction_t of a script when it is set horizontally. All right-to-left scripts will return HB_DIRECTION_RTL. All left-to-right scripts will return HB_DIRECTION_LTR. Scripts that can be written either horizontally or vertically will return HB_DIRECTION_INVALID. Unknown scripts will return HB_DIRECTION_LTR.

#### Parameters

script | The hb_script_t to query |

#### Returns

The horizontal hb_direction_t of `script`

Since: 0.9.2

### hb_language_from_string ()

    hb_language_t
    hb_language_from_string (const char *str,
                             int len);

Converts `str` representing a BCP 47 language tag to the corresponding hb_language_t.

#### Parameters

str | a string representing a BCP 47 language tag. | [array length=len][element-type uint8_t]
len | length of the `str` , or -1 if it is `NULL`-terminated. |

#### Returns

The hb_language_t corresponding to the BCP 47 language tag.

[transfer none]

Since: 0.9.2

### hb_language_to_string ()

    const char *
    hb_language_to_string (hb_language_t language);

Converts an hb_language_t to a string.

#### Parameters

language | The hb_language_t to convert |

#### Returns

A `NULL`-terminated string representing the `language` . Must not be freed by the caller.

[transfer none]

Since: 0.9.2

### hb_language_get_default ()

    hb_language_t
    hb_language_get_default (void);

Fetch the default language from current locale.

Note that the first time this function is called, it calls "setlocale (LC_CTYPE, nullptr)" to fetch current locale. The underlying setlocale function is, in many implementations, NOT threadsafe. To avoid problems, call this function once before multiple threads can call it. This function is only used from `hb_buffer_guess_segment_properties()` by HarfBuzz itself.

#### Returns

The default language of the locale as an hb_language_t.

[transfer none]

Since: 0.9.2

### hb_feature_from_string ()

    hb_bool_t
    hb_feature_from_string (const char *str,
                            int len,
                            hb_feature_t *feature);

Parses a string into a hb_feature_t.

The format for specifying feature strings follows. All valid CSS font-feature-settings values other than 'normal' and the global values are also accepted, though not documented below. CSS string escapes are not supported.

The range indices refer to the positions between Unicode characters. The position before the first character is always 0.

The format is Python-esque. Here is how it all works:

Syntax | Value | Start | End |
Setting value: |  |  |  |
kern | 1 | 0 | ∞ | Turn feature on
+kern | 1 | 0 | ∞ | Turn feature on
-kern | 0 | 0 | ∞ | Turn feature off
kern=0 | 0 | 0 | ∞ | Turn feature off
kern=1 | 1 | 0 | ∞ | Turn feature on
aalt=2 | 2 | 0 | ∞ | Choose 2nd alternate
Setting index: |  |  |  |
kern[] | 1 | 0 | ∞ | Turn feature on
kern[:] | 1 | 0 | ∞ | Turn feature on
kern[5:] | 1 | 5 | ∞ | Turn feature on, partial
kern[:5] | 1 | 0 | 5 | Turn feature on, partial
kern[3:5] | 1 | 3 | 5 | Turn feature on, range
kern[3] | 1 | 3 | 3+1 | Turn feature on, single char
Mixing it all: |  |  |  |
aalt[3:5]=2 | 2 | 3 | 5 | Turn 2nd alternate on for range

#### Parameters

str | a string to parse. | [array length=len][element-type uint8_t]
len | length of `str` , or -1 if string is `NULL` terminated |
feature | the hb_feature_t to initialize with the parsed values. | [out]

#### Returns

`true` if `str` is successfully parsed, `false` otherwise

Since: 0.9.5

### hb_feature_to_string ()

    void
    hb_feature_to_string (hb_feature_t *feature,
                          char *buf,
                          unsigned int size);

Converts a hb_feature_t into a `NULL`-terminated string in the format understood by `hb_feature_from_string()`. The client in responsible for allocating big enough size for `buf` , 128 bytes is more than enough.

#### Parameters

feature | an hb_feature_t to convert |
buf | output string. | [array length=size][out]
size | the allocated size of `buf` |

Since: 0.9.5

### hb_variation_from_string ()

    hb_bool_t
    hb_variation_from_string (const char *str,
                              int len,
                              hb_variation_t *variation);

Since: 1.4.2

### hb_variation_to_string ()

    void
    hb_variation_to_string (hb_variation_t *variation,
                            char *buf,
                            unsigned int size);

Since: 1.4.2

### hb_destroy_func_t ()

    void
    (*hb_destroy_func_t) (void *user_data);

### HB_TAG()

    #define HB_TAG(c1,c2,c3,c4) ((hb_tag_t)((((uint32_t)(c1)&0xFF)<<24)|(((uint32_t)(c2)&0xFF)<<16)|(((uint32_t)(c3)&0xFF)<<8)|((uint32_t)(c4)&0xFF)))

Constructs an hb_tag_t from four characters.

### HB_UNTAG()

    #define HB_UNTAG(tag)   (uint8_t)(((tag)>>24)&0xFF), (uint8_t)(((tag)>>16)&0xFF), (uint8_t)(((tag)>>8)&0xFF), (uint8_t)((tag)&0xFF)

Extracts the characters from an hb_tag_t.

### HB_DIRECTION_REVERSE()

    #define HB_DIRECTION_REVERSE(dir) ((hb_direction_t) (((unsigned int) (dir)) ^ 1))

Reverses a text direction. Requires that the direction be valid.

#### Parameters

dir | hb_direction_t to reverse |

### HB_DIRECTION_IS_BACKWARD()

    #define HB_DIRECTION_IS_BACKWARD(dir) ((((unsigned int) (dir)) & ~2U) == 5)

Tests whether a text direction moves backward (from right to left, or from bottom to top). Requires that the direction be valid.

#### Parameters

dir | hb_direction_t to test |

### HB_DIRECTION_IS_FORWARD()

    #define HB_DIRECTION_IS_FORWARD(dir) ((((unsigned int) (dir)) & ~2U) == 4)

Tests whether a text direction moves forward (from left to right, or from top to bottom). Requires that the direction be valid.

#### Parameters

dir | hb_direction_t to test |

### HB_DIRECTION_IS_HORIZONTAL()

    #define HB_DIRECTION_IS_HORIZONTAL(dir) ((((unsigned int) (dir)) & ~1U) == 4)

Tests whether a text direction is horizontal. Requires that the direction be valid.

#### Parameters

dir | hb_direction_t to test |

### HB_DIRECTION_IS_VALID()

    #define HB_DIRECTION_IS_VALID(dir) ((((unsigned int) (dir)) & ~3U) == 4)

Tests whether a text direction is valid.

#### Parameters

dir | hb_direction_t to test |

### HB_DIRECTION_IS_VERTICAL()

    #define HB_DIRECTION_IS_VERTICAL(dir) ((((unsigned int) (dir)) & ~1U) == 6)

Tests whether a text direction is vertical. Requires that the direction be valid.

#### Parameters

dir | hb_direction_t to test |

## Types and Values

### hb_bool_t

    typedef int hb_bool_t;

Data type for booleans.

### hb_codepoint_t

    typedef uint32_t hb_codepoint_t;

Data type for holding Unicode codepoints. Also used to hold glyph IDs.

### enum hb_direction_t

The direction of a text segment or buffer.

A segment can also be tested for horizontal or vertical orientation (irrespective of specific direction) with `HB_DIRECTION_IS_HORIZONTAL()` or `HB_DIRECTION_IS_VERTICAL()`.

#### Members

HB_DIRECTION_INVALID | Initial, unset direction. |
HB_DIRECTION_LTR | Text is set horizontally from left to right. |
HB_DIRECTION_RTL | Text is set horizontally from right to left. |
HB_DIRECTION_TTB | Text is set vertically from top to bottom. |
HB_DIRECTION_BTT | Text is set vertically from bottom to top. |

### hb_language_t

    typedef const struct hb_language_impl_t *hb_language_t;

### hb_feature_t

    typedef struct {
      hb_tag_t      tag;
      uint32_t      value;
      unsigned int  start;
      unsigned int  end;
    } hb_feature_t;

The hb_feature_t is the structure that holds information about requested feature application. The feature will be applied with the given value to all glyphs which are in clusters between `start` (inclusive) and `end` (exclusive). Setting start to `HB_FEATURE_GLOBAL_START` and end to `HB_FEATURE_GLOBAL_END` specifies that the feature always applies to the entire buffer.

#### Members

hb_tag_t `tag`; | The hb_tag_t tag of the feature |
uint32_t `value`; | The value of the feature. 0 disables the feature, non-zero (usually 1) enables the feature. For features implemented as lookup type 3 (like 'salt') the `value` is a one based index into the alternates. |
unsigned int `start`; | the cluster to start applying this feature setting (inclusive). |
unsigned int `end`; | the cluster to end applying this feature setting (exclusive). |

### hb_variation_t

    typedef struct {
      hb_tag_t tag;
      float    value;
    } hb_variation_t;

Data type for holding variation data. Registered OpenType variation-axis tags are listed at https://docs.microsoft.com/en-us/typography/opentype/spec/dvaraxisreg

#### Members

hb_tag_t `tag`; | The hb_tag_t tag of the variation-axis name |
float `value`; | The value of the variation axis |

Since: 1.4.2

### hb_mask_t

    typedef uint32_t hb_mask_t;

Data type for bitmasks.

### hb_position_t

    typedef int32_t hb_position_t;

Data type for holding a single coordinate value. Contour points and other multi-dimensional data are stored as tuples of hb_position_t's.

### hb_tag_t

    typedef uint32_t hb_tag_t;

### enum hb_script_t

Data type for scripts. Each hb_script_t's value is an hb_tag_t corresponding to the four-letter values defined by ISO 15924.

See also the Script (sc) property of the Unicode Character Database.

#### Members

HB_SCRIPT_BASSA_VAH |  |
HB_SCRIPT_ADLAM |  |
HB_SCRIPT_MASARAM_GONDI |  |
HB_SCRIPT_DOGRA |  |
HB_SCRIPT_ELYMAIC |  |
HB_SCRIPT_CHORASMIAN |  |
HB_SCRIPT_INVALID | HB_TAG_NONE |
_HB_SCRIPT_MAX_VALUE |  |
_HB_SCRIPT_MAX_VALUE_SIGNED |  |

### hb_user_data_key_t

    typedef struct {
    } hb_user_data_key_t;

Data structure for holding user-data keys.

### hb_var_int_t

### HB_TAG_NONE

    #define HB_TAG_NONE HB_TAG(0,0,0,0)

### HB_TAG_MAX

    #define HB_TAG_MAX HB_TAG(0xff,0xff,0xff,0xff)

### HB_TAG_MAX_SIGNED

    #define HB_TAG_MAX_SIGNED HB_TAG(0x7f,0xff,0xff,0xff)

### HB_LANGUAGE_INVALID

    #define HB_LANGUAGE_INVALID ((hb_language_t) 0)

### HB_FEATURE_GLOBAL_END

    #define HB_FEATURE_GLOBAL_END ((unsigned int) -1)

Since: 2.0.0

### HB_FEATURE_GLOBAL_START

    #define HB_FEATURE_GLOBAL_START 0

Since: 2.0.0