InfTextChunk

InfTextChunk — A chunk of text written by various authors

Stability Level

Unstable, unless otherwise indicated

Synopsis

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

                    InfTextChunk;
struct              InfTextChunkIter;
InfTextChunk *      inf_text_chunk_new                  (const gchar *encoding);
InfTextChunk *      inf_text_chunk_copy                 (InfTextChunk *self);
void                inf_text_chunk_free                 (InfTextChunk *self);
const gchar *       inf_text_chunk_get_encoding         (InfTextChunk *self);
guint               inf_text_chunk_get_length           (InfTextChunk *self);
InfTextChunk *      inf_text_chunk_substring            (InfTextChunk *self,
                                                         guint begin,
                                                         guint length);
void                inf_text_chunk_insert_text          (InfTextChunk *self,
                                                         guint offset,
                                                         gconstpointer text,
                                                         gsize bytes,
                                                         guint length,
                                                         guint author);
void                inf_text_chunk_insert_chunk         (InfTextChunk *self,
                                                         guint offset,
                                                         InfTextChunk *text);
void                inf_text_chunk_erase                (InfTextChunk *self,
                                                         guint begin,
                                                         guint length);
gpointer            inf_text_chunk_get_text             (InfTextChunk *self,
                                                         gsize *length);
gboolean            inf_text_chunk_equal                (InfTextChunk *self,
                                                         InfTextChunk *other);
gboolean            inf_text_chunk_iter_init_begin      (InfTextChunk *self,
                                                         InfTextChunkIter *iter);
gboolean            inf_text_chunk_iter_init_end        (InfTextChunk *self,
                                                         InfTextChunkIter *iter);
gboolean            inf_text_chunk_iter_next            (InfTextChunkIter *iter);
gboolean            inf_text_chunk_iter_prev            (InfTextChunkIter *iter);
gconstpointer       inf_text_chunk_iter_get_text        (InfTextChunkIter *iter);
guint               inf_text_chunk_iter_get_offset      (InfTextChunkIter *iter);
guint               inf_text_chunk_iter_get_length      (InfTextChunkIter *iter);
gsize               inf_text_chunk_iter_get_bytes       (InfTextChunkIter *iter);
guint               inf_text_chunk_iter_get_author      (InfTextChunkIter *iter);

Object Hierarchy

  GBoxed
   +----InfTextChunk

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.

Details

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.


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.

encoding :

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

Returns :

A new InfTextChunk.

inf_text_chunk_copy ()

InfTextChunk *      inf_text_chunk_copy                 (InfTextChunk *self);

Returns a copy of self.

self :

A InfTextChunk.

Returns :

A new InfTextChunk.

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().

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.

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.

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.

self :

A InfTextChunk.

begin :

A character offset into self.

length :

The length of the text to extract.

Returns :

A new InfTextChunk.

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.

self :

A InfTextChunk.

offset :

Character offset at which to insert text

text :

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.

self :

A InfTextChunk.

offset :

Character offset at which to insert text.

text :

Chunk to insert into self.

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.

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.

self :

A InfTextChunk.

length :

Location to write the number of bytes to, or NULL.

Returns :

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

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.

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.

self :

A InfTextChunk.

iter :

A InfTextChunkIter.

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.

self :

A InfTextChunk.

iter :

A InfTextChunkIter.

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.

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.

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.

iter :

An initialized InfTextChunkIter.

Returns :

The text of the segment iter points to.

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.

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.

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.

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.

iter :

An initialized InfTextChunkIter.

Returns :

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

See Also

InfTextBuffer