Top | ![]() |
![]() |
![]() |
![]() |
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.
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.
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.
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]
InfTextChunk *
inf_text_chunk_copy (InfTextChunk *self
);
Returns a copy of self
.
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()
.
const gchar *
inf_text_chunk_get_encoding (InfTextChunk *self
);
Returns the character encoding in which the content of self
is encoded.
guint
inf_text_chunk_get_length (InfTextChunk *self
);
Returns the number of characters contained in self
.
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 |
|
length |
The length of the text to extract. |
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
|
|
bytes |
Number of bytes of |
|
length |
Number of characters contained in |
|
author |
User that wrote |
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 |
[transfer none] |
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 |
|
length |
Number of characters to erase. |
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.
Content of
self
. Free with g_free()
if no longer in use.
[type guint8*][array length=length][transfer full]
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.
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
.
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
.
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
.
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
.
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.
guint
inf_text_chunk_iter_get_offset (InfTextChunkIter *iter
);
Returns the offset of the first character in the segment iter
points to.
guint
inf_text_chunk_iter_get_length (InfTextChunkIter *iter
);
Returns the number of characters in the segment iter
points to.
gsize
inf_text_chunk_iter_get_bytes (InfTextChunkIter *iter
);
Returns the number of bytes in the segment iter
points to.
guint
inf_text_chunk_iter_get_author (InfTextChunkIter *iter
);
Returns the user ID of the author of the segment iter
points to.
typedef struct _InfTextChunk InfTextChunk;
InfTextChunk is an opaque data type. You should only access it via the public API functions.
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.