Miscellaneous Utilities: Pango Reference Manual

## Miscellaneous Utilities Miscellaneous Utilities — Various convenience and utility functions |

## Functions

char ** | pango_split_file_list ()
char * | pango_trim_string ()
gint | pango_read_line ()
gboolean | pango_skip_space ()
gboolean | pango_scan_word ()
gboolean | pango_scan_string ()
gboolean | pango_scan_int ()
gboolean | pango_parse_enum ()
gboolean | pango_parse_style ()
gboolean | pango_parse_variant ()
gboolean | pango_parse_weight ()
gboolean | pango_parse_stretch ()
guint8 * | pango_log2vis_get_embedding_levels ()
gboolean | pango_is_zero_width ()
void | pango_quantize_line_geometry ()

## Description

The functions and utilities in this section are mostly used from Pango backends and modules, but may be useful for other purposes too.

## Functions

### pango_split_file_list ()

    char **
    pango_split_file_list (const char *str);

`pango_split_file_list` has been deprecated since version 1.38 and should not be used in newly-written code.

Splits a `G_SEARCHPATH_SEPARATOR`-separated list of files, stripping white space and substituting ~/ with $HOME/.

#### Parameters

str | a `G_SEARCHPATH_SEPARATOR` separated list of filenames |

#### Returns

a list of strings to be freed with `g_strfreev()`.

[transfer full][array zero-terminated=1]

### pango_trim_string ()

    char *
    pango_trim_string (const char *str);

`pango_trim_string` has been deprecated since version 1.38 and should not be used in newly-written code.

Trims leading and trailing whitespace from a string.

#### Parameters

str | a string |

#### Returns

A newly-allocated string that must be freed with `g_free()`

### pango_read_line ()

    gint
    pango_read_line (FILE *stream,
                     GString *str);

`pango_read_line` has been deprecated since version 1.38 and should not be used in newly-written code.

Reads an entire line from a file into a buffer. Lines may be delimited with '\n', '\r', '\n\r', or '\r\n'. The delimiter is not written into the buffer. Text after a '#' character is treated as a comment and skipped. '\' can be used to escape a # character. '\' proceeding a line delimiter combines adjacent lines. A '\' proceeding any other character is ignored and written into the output buffer unmodified.

#### Parameters

stream | a stdio stream |
str | GString buffer into which to write the result |

#### Returns

0 if the stream was already at an `EOF` character, otherwise the number of lines read (this is useful for maintaining a line number counter which doesn't combine lines with '\')

### pango_skip_space ()

    gboolean
    pango_skip_space (const char **pos);

`pango_skip_space` has been deprecated since version 1.38 and should not be used in newly-written code.

Skips 0 or more characters of white space.

#### Parameters

pos | in/out string position. | [inout]

#### Returns

`FALSE` if skipping the white space leaves the position at a '\0' character.

### pango_scan_word ()

    gboolean
    pango_scan_word (const char **pos,
                     GString *out);

`pango_scan_word` has been deprecated since version 1.38 and should not be used in newly-written code.

Scans a word into a GString buffer. A word consists of [A-Za-z_] followed by zero or more [A-Za-z_0-9] Leading white space is skipped.

#### Parameters

pos | in/out string position. | [inout]
out | a GString into which to write the result |

#### Returns

`FALSE` if a parse error occurred.

### pango_scan_string ()

    gboolean
    pango_scan_string (const char **pos,
                       GString *out);

`pango_scan_string` has been deprecated since version 1.38 and should not be used in newly-written code.

Scans a string into a GString buffer. The string may either be a sequence of non-white-space characters, or a quoted string with '"'. Instead a quoted string, '\"' represents a literal quote. Leading white space outside of quotes is skipped.

#### Parameters

pos | in/out string position. | [inout]
out | a GString into which to write the result |

#### Returns

`FALSE` if a parse error occurred.

### pango_scan_int ()

    gboolean
    pango_scan_int (const char **pos,
                    int *out);

`pango_scan_int` has been deprecated since version 1.38 and should not be used in newly-written code.

Scans an integer. Leading white space is skipped.

#### Parameters

pos | in/out string position. | [inout]
out | an int into which to write the result. | [out]

#### Returns

`FALSE` if a parse error occurred.

### pango_parse_enum ()

    gboolean
    pango_parse_enum (GType type,
                      const char *str,
                      int *value,
                      gboolean warn,
                      char **possible_values);

`pango_parse_enum` has been deprecated since version 1.38 and should not be used in newly-written code.

Parses an enum type and stores the result in `value` .

If `str` does not match the nick name of any of the possible values for the enum and is not an integer, `FALSE` is returned, a warning is issued if `warn` is `TRUE`, and a string representing the list of possible values is stored in `possible_values` . The list is slash-separated, eg. "none/start/middle/end". If failed and `possible_values` is not `NULL`, returned string should be freed using `g_free()`.

#### Parameters

type | enum type to parse, eg. `PANGO_TYPE_ELLIPSIZE_MODE`. |
str | string to parse. May be `NULL`. | [allow-none]
value | integer to store the result in, or `NULL`. | [out][allow-none]
warn | if `TRUE`, issue a `g_warning()` on bad input. |
possible_values | place to store list of possible values on failure, or `NULL`. | [out][allow-none]

#### Returns

`TRUE` if `str` was successfully parsed.

Since: 1.16

### pango_parse_style ()

    gboolean
    pango_parse_style (const char *str,
                       PangoStyle *style,
                       gboolean warn);

Parses a font style. The allowed values are "normal", "italic" and "oblique", case variations being ignored.

#### Parameters

str | a string to parse. |
style | a PangoStyle to store the result in. | [out]
warn | if `TRUE`, issue a `g_warning()` on bad input. |

#### Returns

`TRUE` if `str` was successfully parsed.

### pango_parse_variant ()

    gboolean
    pango_parse_variant (const char *str,
                         PangoVariant *variant,
                         gboolean warn);

Parses a font variant. The allowed values are "normal" and "smallcaps" or "small_caps", case variations being ignored.

#### Parameters

str | a string to parse. |
variant | a PangoVariant to store the result in. | [out]
warn | if `TRUE`, issue a `g_warning()` on bad input. |

#### Returns

`TRUE` if `str` was successfully parsed.

### pango_parse_weight ()

    gboolean
    pango_parse_weight (const char *str,
                        PangoWeight *weight,
                        gboolean warn);

Parses a font weight. The allowed values are "heavy", "ultrabold", "bold", "normal", "light", "ultraleight" and integers. Case variations are ignored.

#### Parameters

str | a string to parse. |
weight | a PangoWeight to store the result in. | [out]
warn | if `TRUE`, issue a `g_warning()` on bad input. |

#### Returns

`TRUE` if `str` was successfully parsed.

### pango_parse_stretch ()

    gboolean
    pango_parse_stretch (const char *str,
                         PangoStretch *stretch,
                         gboolean warn);

Parses a font stretch. The allowed values are "ultra_condensed", "extra_condensed", "condensed", "semi_condensed", "normal", "semi_expanded", "expanded", "extra_expanded" and "ultra_expanded". Case variations are ignored and the '_' characters may be omitted.

#### Parameters

str | a string to parse. |
stretch | a PangoStretch to store the result in. | [out]
warn | if `TRUE`, issue a `g_warning()` on bad input. |

#### Returns

`TRUE` if `str` was successfully parsed.

### pango_log2vis_get_embedding_levels ()

    guint8 *
    pango_log2vis_get_embedding_levels (const gchar *text,
                                        int length,
                                        PangoDirection *pbase_dir);

This will return the bidirectional embedding levels of the input paragraph as defined by the Unicode Bidirectional Algorithm available at:

http://www.unicode.org/reports/tr9/

If the input base direction is a weak direction, the direction of the characters in the text will determine the final resolved direction.

#### Parameters

text | the text to itemize. |
length | the number of bytes (not characters) to process, or -1 if `text` is nul-terminated and the length should be calculated. |
pbase_dir | input base direction, and output resolved direction. |

#### Returns

a newly allocated array of embedding levels, one item per character (not byte), that should be freed using g_free.

Since: 1.4

### pango_is_zero_width ()

    gboolean
    pango_is_zero_width (gunichar ch);

Checks `ch` to see if it is a character that should not be normally rendered on the screen. This includes all Unicode characters with "ZERO WIDTH" in their name, as well as bidi formatting characters, and a few other ones. This is totally different from `g_unichar_iszerowidth()` and is at best misnamed.

#### Parameters

ch | a Unicode character |

#### Returns

`TRUE` if `ch` is a zero-width character, `FALSE` otherwise

Since: 1.10

### pango_quantize_line_geometry ()

    void
    pango_quantize_line_geometry (int *thickness,
                                  int *position);

Quantizes the thickness and position of a line, typically an underline or strikethrough, to whole device pixels, that is integer multiples of `PANGO_SCALE`. The purpose of this function is to avoid such lines looking blurry.

Care is taken to make sure `thickness` is at least one pixel when this function returns, but returned `position` may become zero as a result of rounding.

#### Parameters

thickness | pointer to the thickness of a line, in Pango units. | [inout]
position | corresponding position. | [inout]

Since: 1.12

## Types and Values