InfTextChunk: libinftext-0.7 Reference Manual

## InfTextChunk InfTextChunk — A chunk of text written by various authors |

## Stability Level

Unstable, unless otherwise indicated

## Functions

InfTextChunkIter * | inf_text_chunk_iter_copy ()
void | inf_text_chunk_iter_free ()
InfTextChunk * | inf_text_chunk_new ()
InfTextChunk * | inf_text_chunk_copy ()
void | inf_text_chunk_free ()
const gchar * | inf_text_chunk_get_encoding ()
guint | inf_text_chunk_get_length ()
InfTextChunk * | inf_text_chunk_substring ()
void | inf_text_chunk_insert_text ()
void | inf_text_chunk_insert_chunk ()
void | inf_text_chunk_erase ()
gpointer | inf_text_chunk_get_text ()
gboolean | inf_text_chunk_equal ()
gboolean | inf_text_chunk_iter_init_begin ()
gboolean | inf_text_chunk_iter_init_end ()
gboolean | inf_text_chunk_iter_next ()
gboolean | inf_text_chunk_iter_prev ()
gconstpointer | inf_text_chunk_iter_get_text ()
guint | inf_text_chunk_iter_get_offset ()
guint | inf_text_chunk_iter_get_length ()
gsize | inf_text_chunk_iter_get_bytes ()
guint | inf_text_chunk_iter_get_author ()

## Types and Values

| InfTextChunk
struct | InfTextChunkIter

## Object Hierarchy

        GBoxed
        ├── InfTextChunk
        ╰── InfTextChunkIter

## Includes

    #include <libinftext/inf-text-chunk.h>

## Description

InfTextChunk represents a chunk of text where different parts of it can be written by different authors. The InfTextChunk API can be used like a normal string API, except that apart from the text itself it also stores the author information.

An InfTextChunk is made up of segments, where each segment represents a contiguous piece of text which is written by the same user. The InfTextChunkIter functionality can be used to iterate over the segments of a chunk.

The InfTextChunk API works with characters, not bytes, i.e. all offsets are given in number of characters. This ensures that unicode strings cannot be torn apart in the middle of a multibyte sequence. The encoding of an InfTextChunk is not fixed, but it can be freely chosen. InfTextChunk then uses iconv to convert between bytes and character offsets where necessary. For a small set of selected encodings which are very popular, most notably UTF-8, there exist more optimized code paths to do the conversion.

## Functions

### inf_text_chunk_iter_copy ()

    InfTextChunkIter *
    inf_text_chunk_iter_copy (const InfTextChunkIter *iter);

Makes a dynamically-allocated copy of `iter` . This is typically not needed because InfTextChunkIter can be copied by value, however it might be useful to language bindings.

#### Parameters

iter | A InfTextChunkIter. |

#### Returns

A copy of `iter` . Free with `inf_text_chunk_iter_free()`.

[transfer full]

### inf_text_chunk_iter_free ()

    void
    inf_text_chunk_iter_free (InfTextChunkIter *iter);

Frees all resources allocated with `inf_text_chunk_iter_copy()`. Must not be used with stack-allocated InfTextChunkIters.

#### Parameters

iter | The InfTextChunkIter to free. |

### inf_text_chunk_new ()

    InfTextChunk *
    inf_text_chunk_new (const gchar *encoding);

Creates a new InfTextChunk with no initial content that holds text in the given encoding. TODO: Allow binary data with `NULL` encoding.

[constructor]

#### Parameters

encoding | A content encoding, such as "UTF-8" or "LATIN1". |

#### Returns

A new InfTextChunk.

[transfer full]

### inf_text_chunk_copy ()

    InfTextChunk *
    inf_text_chunk_copy (InfTextChunk *self);

Returns a copy of `self` .

#### Parameters

self | A InfTextChunk. |

#### Returns

A new InfTextChunk.

[transfer full]

### inf_text_chunk_free ()

    void
    inf_text_chunk_free (InfTextChunk *self);

Frees a InfTextChunk allocated with `inf_text_chunk_new()`, `inf_text_chunk_copy()` or `inf_text_chunk_substring()`.

#### Parameters

self | A InfTextChunk. |

### inf_text_chunk_get_encoding ()

    const gchar *
    inf_text_chunk_get_encoding (InfTextChunk *self);

Returns the character encoding in which the content of `self` is encoded.

#### Parameters

self | A InfTextChunk. |

#### Returns

The encoding of `self` .

### inf_text_chunk_get_length ()

    guint
    inf_text_chunk_get_length (InfTextChunk *self);

Returns the number of characters contained in `self` .

#### Parameters

self | A InfTextChunk. |

#### Returns

The number of characters of `self` .

### inf_text_chunk_substring ()

    InfTextChunk *
    inf_text_chunk_substring (InfTextChunk *self,
                              guint begin,
                              guint length);

Returns a new InfTextChunk containing a substring of `self` , beginning at character offset `begin` and `length` characters long.

#### Parameters

self | A InfTextChunk. |
begin | A character offset into `self` . |
length | The length of the text to extract. |

#### Returns

A new InfTextChunk.

[transfer full]

### inf_text_chunk_insert_text ()

    void
    inf_text_chunk_insert_text (InfTextChunk *self,
                                guint offset,
                                gconstpointer text,
                                gsize bytes,
                                guint length,
                                guint author);

Inserts text written by `author` into `self` . `text` is expected to be in the chunk's encoding.

#### Parameters

self | A InfTextChunk. |
offset | Character offset at which to insert text |
text (type const guint8*) (array length=bytes) (transfer none) | Text to insert. |
length | Number of characters contained in `text` . |
bytes | Number of bytes of `text` . |
author | User that wrote `text` . |

### inf_text_chunk_insert_chunk ()

    void
    inf_text_chunk_insert_chunk (InfTextChunk *self,
                                 guint offset,
                                 InfTextChunk *text);

Inserts `text` into `self` at position `offset` . `text` and `self` must have the same encoding.

#### Parameters

self | A InfTextChunk. |
offset | Character offset at which to insert text. |
text | Chunk to insert into `self` . | [transfer none]

### inf_text_chunk_erase ()

    void
    inf_text_chunk_erase (InfTextChunk *self,
                          guint begin,
                          guint length);

Removes `length` characters of `self` , starting from character offset `begin` .

#### Parameters

self | A InfTextChunk. |
begin | A character offset into `self` . |
length | Number of characters to erase. |

### inf_text_chunk_get_text ()

    gpointer
    inf_text_chunk_get_text (InfTextChunk *self,
                             gsize *length);

Returns the content of `self` as an array. The text is encoded in `self` 's encoding. `length` is set to the number of bytes in the returned buffer, if non-`NULL`. The result is _not_ zero-terminated.

#### Parameters

self | A InfTextChunk. |
length | Location to write the number of bytes to, or `NULL`. | [out]

#### Returns

Content of `self` . Free with `g_free()` if no longer in use.

[type guint8*][array length=length][transfer full]

### inf_text_chunk_equal ()

    gboolean
    inf_text_chunk_equal (InfTextChunk *self,
                          InfTextChunk *other);

Returns whether the two text chunks contain the same text and the same segments were written by the same authors.

#### Parameters

self | A InfTextChunk. |
other | Another InfTextChunk. |

#### Returns

Whether the two chunks are equal.

### inf_text_chunk_iter_init_begin ()

    gboolean
    inf_text_chunk_iter_init_begin (InfTextChunk *self,
                                    InfTextChunkIter *iter);

Sets `iter` to point to the first segment of `self` . If there are no segments (i.e. `self` is empty), `iter` is left untouched and the function returns `FALSE`.

#### Parameters

self | A InfTextChunk. |
iter | A InfTextChunkIter. | [out]

#### Returns

Whether `iter` was set.

### inf_text_chunk_iter_init_end ()

    gboolean
    inf_text_chunk_iter_init_end (InfTextChunk *self,
                                  InfTextChunkIter *iter);

Sets `iter` to point to the last segment of `self` . If there are no segments (i.e. `self` is empty), `iter` is left untouched and the function returns `FALSE`.

#### Parameters

self | A InfTextChunk. |
iter | A InfTextChunkIter. | [out]

#### Returns

Whether `iter` was set.

### inf_text_chunk_iter_next ()

    gboolean
    inf_text_chunk_iter_next (InfTextChunkIter *iter);

Sets `iter` to point to the next segment. If `iter` already points to the last segment, the function returns `FALSE`.

#### Parameters

iter | An initialized InfTextChunkIter. |

#### Returns

Whether `iter` was set.

### inf_text_chunk_iter_prev ()

    gboolean
    inf_text_chunk_iter_prev (InfTextChunkIter *iter);

Sets `iter` to point to the previous segment. If `iter` already points to the first segment, the function returns `FALSE`.

#### Parameters

iter | An initialized InfTextChunkIter. |

#### Returns

Whether `iter` has changed.

### inf_text_chunk_iter_get_text ()

    gconstpointer
    inf_text_chunk_iter_get_text (InfTextChunkIter *iter);

Returns the text of the segment `iter` points to. The text is in the underlaying InfTextChunk's encoding.

#### Parameters

iter | An initialized InfTextChunkIter. |

#### Returns

The text of the segment `iter` points to.

[transfer none]

### inf_text_chunk_iter_get_offset ()

    guint
    inf_text_chunk_iter_get_offset (InfTextChunkIter *iter);

Returns the offset of the first character in the segment `iter` points to.

#### Parameters

iter | An initialized InfTextChunkIter. |

#### Returns

The offset of the first characters in the segment `iter` points to.

### inf_text_chunk_iter_get_length ()

    guint
    inf_text_chunk_iter_get_length (InfTextChunkIter *iter);

Returns the number of characters in the segment `iter` points to.

#### Parameters

iter | An initialized InfTextChunkIter. |

#### Returns

The number of characters in the segment `iter` points to.

### inf_text_chunk_iter_get_bytes ()

    gsize
    inf_text_chunk_iter_get_bytes (InfTextChunkIter *iter);

Returns the number of bytes in the segment `iter` points to.

#### Parameters

iter | An initialized InfTextChunkIter. |

#### Returns

The number of bytes in the segment `iter` points to.

### inf_text_chunk_iter_get_author ()

    guint
    inf_text_chunk_iter_get_author (InfTextChunkIter *iter);

Returns the user ID of the author of the segment `iter` points to.

#### Parameters

iter | An initialized InfTextChunkIter. |

#### Returns

The user ID of the author of the segment `iter` points to.

## Types and Values

### InfTextChunk

    typedef struct _InfTextChunk InfTextChunk;

InfTextChunk is an opaque data type. You should only access it via the public API functions.

### struct InfTextChunkIter

    struct InfTextChunkIter {
    };

InfTextChunkIter is an opaque data type. You should only access it via the public API functions.

InfTextChunkIter can be safely allocated on the stack and copied by value. Use `inf_text_chunk_iter_init_begin()` or `inf_text_chunk_iter_init_end()` to initialize a InfTextChunkIter. There is no deinitialization required. A InfTextChunkIter is valid as long as the chunk is not modified.

## See Also

InfTextBuffer