## GflsBytesRegion

GflsBytesRegion — A group of sub-regions of a GBytes

## Functions

void | gfls_bytes_region_free ()
gboolean | gfls_bytes_region_match_bytes ()
gchar * | gfls_bytes_region_to_string ()
GflsBytesRegionIter * | gfls_bytes_region_get_start_iter ()
gboolean | gfls_bytes_region_iter_is_end ()
void | gfls_bytes_region_iter_get_sub_region ()
void | gfls_bytes_region_iter_next ()
void | gfls_bytes_region_iter_free ()

## Types and Values

| GflsBytesRegion
| GflsBytesRegionIter

## Includes

    #include <gfls/gfls.h>

## Description

GflsBytesRegion permits to store a group of sub-regions of a GBytes. Use a GflsBytesRegionBuilder to construct a GflsBytesRegion.

Use-case: the region delimits valid (or invalid) bytes in a specified character encoding, possibly after a conversion (or at least a validation).

To iterate through the sub-regions, you need to use a GflsBytesRegionIter:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35

    GflsBytesRegion *region;
    GflsBytesRegionIter *iter;
    GBytes *bytes;

    if (!gfls_bytes_region_match_bytes (region, bytes))
    {
            return;
    }

    iter = gfls_bytes_region_get_start_iter (region);

    while (!gfls_bytes_region_iter_is_end (region, iter))
    {
            gsize sub_region_size = 0;
            gsize offset = 0;
            gboolean is_part_of_region = FALSE;
            gconstpointer sub_region_data;

            gfls_bytes_region_iter_get_sub_region (region,
                                                   iter,
                                                   &sub_region_size,
                                                   &offset,
                                                   &is_part_of_region);

            sub_region_data = g_bytes_get_region (bytes,
                                                  sub_region_size,
                                                  offset,
                                                  1);

            // Do something useful with the sub-region.

            gfls_bytes_region_iter_next (region, iter);
    }

    gfls_bytes_region_iter_free (region, iter);

This traverses the GBytes from start to end. `is_part_of_region` permits to know if the sub-region is part of the GflsBytesRegion or if it is a "hole". (A hole doesn't mean that there are no bytes, the meaning depends on the use-case).

## Functions

### gfls_bytes_region_free ()

    void
    gfls_bytes_region_free (GflsBytesRegion *region);

Frees `region` .

#### Parameters

region | a GflsBytesRegion. | [nullable]

Since: 0.4

### gfls_bytes_region_match_bytes ()

    gboolean
    gfls_bytes_region_match_bytes (GflsBytesRegion *region,
                                   GBytes *bytes);

#### Parameters

region | a GflsBytesRegion. |
bytes | a GBytes. |

#### Returns

whether `region` can be applied to `bytes` (it checks the total size).

Since: 0.4

### gfls_bytes_region_to_string ()

    gchar *
    gfls_bytes_region_to_string (GflsBytesRegion *region);

The format is:

`[offset, sub_region_size, is_part_of_region]\n`

One line per sub-region, in order.

#### Parameters

region | a GflsBytesRegion. |

#### Returns

a string representation of `region` .

[transfer full]

Since: 0.4

### gfls_bytes_region_get_start_iter ()

    GflsBytesRegionIter *
    gfls_bytes_region_get_start_iter (GflsBytesRegion *region);

[skip]

#### Parameters

region | a GflsBytesRegion. |

#### Returns

a new GflsBytesRegionIter located at the beginning. Free with `gfls_bytes_region_iter_free()`.

[transfer full]

Since: 0.4

### gfls_bytes_region_iter_is_end ()

    gboolean
    gfls_bytes_region_iter_is_end (GflsBytesRegion *region,
                                   GflsBytesRegionIter *iter);

#### Parameters

region | a GflsBytesRegion. |
iter | a GflsBytesRegionIter. |

#### Returns

whether `iter` is the end iterator.

Since: 0.4

### gfls_bytes_region_iter_get_sub_region ()

    void
    gfls_bytes_region_iter_get_sub_region (GflsBytesRegion *region,
                                           GflsBytesRegionIter *iter,
                                           gsize *sub_region_size,
                                           gsize *offset,
                                           gboolean *is_part_of_region);

Gets the sub-region at this iterator.

`sub_region_size` and `offset` can be used as arguments to `g_bytes_get_region()`.

`is_part_of_region` has the same meaning as for `gfls_bytes_region_builder_append()`. GflsBytesRegionIter iterates on both the region and the holes, so that the corresponding GBytes is traversed from start to end.

#### Parameters

region | a GflsBytesRegion. |
iter | a GflsBytesRegionIter. It must not be the end iterator. |
sub_region_size | the sub-region size. | [out][not nullable]
offset | the offset to the start of the sub-region. | [out][not nullable]
is_part_of_region | whether the sub-region is part of the region. | [out][not nullable]

Since: 0.4

### gfls_bytes_region_iter_next ()

    void
    gfls_bytes_region_iter_next (GflsBytesRegion *region,
                                 GflsBytesRegionIter *iter);

Moves `iter` to the next sub-region.

If all sub-regions have been traversed, `iter` is set to the end iterator.

#### Parameters

region | a GflsBytesRegion. |
iter | a GflsBytesRegionIter. The end iterator is accepted as an input value. |

Since: 0.4

### gfls_bytes_region_iter_free ()

    void
    gfls_bytes_region_iter_free (GflsBytesRegion *region,
                                 GflsBytesRegionIter *iter);

Frees `iter` .

#### Parameters

region | a GflsBytesRegion. |
iter | a GflsBytesRegionIter. | [nullable]

Since: 0.4

## Types and Values

### GflsBytesRegion

    typedef struct _GflsBytesRegion GflsBytesRegion;

### GflsBytesRegionIter

    typedef struct _GflsBytesRegionIter GflsBytesRegionIter;