| libinftext-0.6 Reference Manual | ||||
|---|---|---|---|---|
| Top | Description | Object Hierarchy | ||||
#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);
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.
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.
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.
|
A content encoding, such as "UTF-8" or "LATIN1". |
Returns : |
A new InfTextChunk. |
InfTextChunk * inf_text_chunk_copy (InfTextChunk *self);
Returns a copy of self.
|
A InfTextChunk. |
Returns : |
A new InfTextChunk. |
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().
|
A InfTextChunk. |
const gchar * inf_text_chunk_get_encoding (InfTextChunk *self);
Returns the character encoding in which the content of self is encoded.
|
A InfTextChunk. |
Returns : |
The encoding of self. |
guint inf_text_chunk_get_length (InfTextChunk *self);
Returns the number of characters contained in self.
|
A InfTextChunk. |
Returns : |
The number of characters of 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.
|
A InfTextChunk. |
|
A character offset into self. |
|
The length of the text to extract. |
Returns : |
A new InfTextChunk. |
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.
|
A InfTextChunk. |
|
Character offset at which to insert text |
|
Text to insert. |
|
Number of bytes of text. |
|
Number of characters contained in text. |
|
User that wrote text. |
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.
|
A InfTextChunk. |
|
Character offset at which to insert text. |
|
Chunk to insert into self. |
void inf_text_chunk_erase (InfTextChunk *self,guint begin,guint length);
Removes length characters of self, starting from character offset begin.
|
A InfTextChunk. |
|
A character offset into self. |
|
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.
|
A InfTextChunk. |
|
Location to write the number of bytes to, or NULL. |
Returns : |
Content of self. Free with g_free() if no longer in use. |
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.
|
A InfTextChunk. |
|
Another InfTextChunk. |
Returns : |
Whether the two chunks are equal. |
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.
|
A InfTextChunk. |
|
A InfTextChunkIter. |
Returns : |
Whether iter was set. |
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.
|
A InfTextChunk. |
|
A InfTextChunkIter. |
Returns : |
Whether iter was set. |
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.
|
An initialized InfTextChunkIter. |
Returns : |
Whether iter was set. |
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.
|
An initialized InfTextChunkIter. |
Returns : |
Whether iter has changed. |
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.
|
An initialized InfTextChunkIter. |
Returns : |
The text of the segment iter points to. |
guint inf_text_chunk_iter_get_offset (InfTextChunkIter *iter);
Returns the offset of the first character in the segment iter points to.
|
An initialized InfTextChunkIter. |
Returns : |
The offset of the first characters 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.
|
An initialized InfTextChunkIter. |
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.
|
An initialized InfTextChunkIter. |
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.
|
An initialized InfTextChunkIter. |
Returns : |
The user ID of the author of the segment iter points to. |