InfTextChunk

InfTextChunk — A chunk of text written by various authors

Stability Level

Unstable, unless otherwise indicated

Functions

Types and Values

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.

 

bytes

Number of bytes of text .

 

length

Number of characters contained in 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