rb-text-helpers

## rb-text-helpers rb-text-helpers — text direction (LTR/RTL) functions |

## Synopsis

    gboolean            rb_text_direction_conflict          (PangoDirection dir1,
                                                             PangoDirection dir2);
    PangoDirection      rb_text_common_direction            (const char *first,
                                                             ...);
    char *              rb_text_cat                         (PangoDirection base_dir,
                                                             ...);

## Description

Provides some helper functions for constructing strings that may include both left-to-right and right-to-left text.

## Details

### rb_text_direction_conflict ()

    gboolean            rb_text_direction_conflict          (PangoDirection dir1,
                                                             PangoDirection dir2);

Direction conflict here means the two directions are defined (non-neutral) and they are different.

`dir1` : | direction A
`dir2` : | direction B
Returns : | `TRUE` if the two directions conflict.

### rb_text_common_direction ()

    PangoDirection      rb_text_common_direction            (const char *first,
                                                             ...);

This functions checks the direction of all given strings and:

1. If all strings are direction neutral, returns `PANGO_DIRECTION_NEUTRAL`;

2. If all strings are either LTR or neutral, returns `PANGO_DIRECTION_LTR`;

3. If all strings are either RTL or neutral, returns `PANGO_DIRECTION_RTL`;

4. If at least one is RTL and one LTR, returns `PANGO_DIRECTION_NEUTRAL`.

Note: neutral (1) and mixed (4) are two very different situations, they share a return code here only because they're the same for our specific use.

`first` : | first string
`...` : | rest of strings, terminated with `NULL`
Returns : | common direction of all strings, as defined above.

### rb_text_cat ()

    char *              rb_text_cat                         (PangoDirection base_dir,
                                                             ...);

This function concatenates strings to a single string, preserving each part's original direction (LTR or RTL) using unicode markup, as detailed here: http://unicode.org/reports/tr9/.

It is called like this:

s = rb_text_cat(base_dir, str1, format1, ..., strN, formatN, `NULL`)

Format is a printf format with exactly one %s. "%s" or "" will insert the string as is.

Any string that is empty ("") will be skipped, its format must still be passed.

A space is inserted between strings.

The algorithm:

1. Caller supplies the base direction of the result in base_dir.

2. Insert either `LRM` or `RLM` at the beginning of the string to set its base direction, according to base_dir.

3. Find the direction of each string using pango.

4. For strings that have the same direction as the base direction, just insert them in.

5. For strings that have the opposite direction than the base one, insert them surrounded with embedding codes `RLE`/`LRE` .. `PDF`.

`base_dir` : | direction of the result string.
`...` : | pairs of strings (content, format) terminated with `NULL`.
Returns : | a new string containing the result.