Welcome to Ωedit™’s API documentation!

For more information, please visit the Ωedit™ Wiki.

Index

byte.h

omega_byte_t definition.

Typedefs

typedef OMEGA_BYTE_T omega_byte_t: omega_byte_t is configured (via OMEGA_BYTE_T in config.h) as a single byte

change.h

Functions that operate on editing changes (omega_change_t).

Enums

enum omega_change_data_storage_t

Storage backing for a change primitive’s data payload.

Values:

enumerator OMEGA_CHANGE_DATA_STORAGE_NONE: No data payload is available for this change.

enumerator OMEGA_CHANGE_DATA_STORAGE_INLINE: Data is stored inline with the change.

enumerator OMEGA_CHANGE_DATA_STORAGE_FILE_BACKED: Data is stored in a session-owned backing file.

enum omega_change_payload_role_t

Payload selector for internal and diagnostic byte access.

Values:

enumerator OMEGA_CHANGE_PAYLOAD_DATA: The primitive data payload.

enumerator OMEGA_CHANGE_PAYLOAD_INVERSE_DATA: Bytes removed by the primitive, when distinct from data.

Functions

int64_t omega_change_get_offset(const omega_change_t *change_ptr)

Given a change, return the original change offset

Parameters:: change_ptr – change to get the original change offset from
Returns:: original change offset

int64_t omega_change_get_length(const omega_change_t *change_ptr)

Given a change, return the original number of bytes deleted, inserted, or overwritten

Parameters:: change_ptr – change to get the original number of bytes from
Returns:: original number of bytes deleted, inserted, or overwritten

int64_t omega_change_get_serial(const omega_change_t *change_ptr)

Given a change, return the change serial number. A negative serial number is an undone change.

Parameters:: change_ptr – change to get the serial number from
Returns:: change serial number

char omega_change_get_kind_as_char(const omega_change_t *change_ptr)

Given a change, return a character representing the kind of change (‘D’, ‘I’, ‘O’, and ‘T’)

Parameters:: change_ptr – change to get the kind from
Returns:: ‘D’ if the change is a delete, ‘I’ if the change is an insert, ‘O’ if the change is an overwrite, and ‘T’ if the change is a transform

int omega_change_get_transaction_bit(const omega_change_t *change_ptr)

Given a change, return the transaction bit (0 or 1)

Parameters:: change_ptr – change to get the transaction bit from
Returns:: transaction bit (0 or 1)

int64_t omega_change_get_transaction_start_serial(const omega_change_t *change_ptr)

Return the first serial of the explicit transaction containing this change.

Parameters:: change_ptr – change to inspect
Returns:: positive transaction-start serial, or 0 when the change is not part of an explicit transaction

const omega_byte_t *omega_change_get_bytes(const omega_change_t *change_ptr)

Given a change, return a pointer to the primitive byte payload.

This is the first-class primitive view of the change data field:

INSERT/OVERWRITE payloads are the inserted or overwritten bytes.
DELETE payloads are exactly the original bytes removed by the edit.
TRANSFORM payloads are a JSON descriptor containing the transform id and arguments.

Use omega_change_get_data_length and omega_change_get_data_storage to interpret the returned pointer.

Parameters:: change_ptr – change to get the primitive byte payload from
Returns:: pointer to primitive data, or NULL when no payload is available or materialization fails

const omega_byte_t *omega_change_get_data(const omega_change_t *change_ptr)

Alias for omega_change_get_bytes.

Parameters:: change_ptr – change to get the primitive data payload from
Returns:: pointer to primitive data, or NULL when no payload is available or materialization fails

int64_t omega_change_get_data_length(const omega_change_t *change_ptr)

Given a change, return the primitive data payload length.

Parameters:: change_ptr – change to inspect
Returns:: primitive data byte count, or 0 when no payload is available

omega_change_data_storage_t omega_change_get_data_storage(const omega_change_t *change_ptr)

Given a change, return how the primitive data payload is stored.

Parameters:: change_ptr – change to inspect
Returns:: primitive data storage kind

int omega_change_is_transform(const omega_change_t *change_ptr)

Given a change, return a non-zero value if this is a transform change.

Parameters:: change_ptr – change to inspect
Returns:: non-zero if the change is a transform, zero otherwise

const char *omega_change_get_transform_id(const omega_change_t *change_ptr)

Given a transform change, return the transform identifier.

Parameters:: change_ptr – transform change to inspect
Returns:: transform identifier, or NULL if this is not a transform change

const char *omega_change_get_transform_options_json(const omega_change_t *change_ptr)

Given a transform change, return the transform options JSON.

Parameters:: change_ptr – transform change to inspect
Returns:: options JSON, or NULL when not available

int64_t omega_change_get_transform_replacement_length(const omega_change_t *change_ptr)

Given a transform change, return the replacement byte length produced by the transform.

Parameters:: change_ptr – transform change to inspect
Returns:: replacement byte length, or -1 if this is not a transform change

int64_t omega_change_get_transform_computed_file_size_before(const omega_change_t *change_ptr)

Given a transform change, return the computed file size before the transform.

Parameters:: change_ptr – transform change to inspect
Returns:: computed file size before the transform, or -1 if this is not a transform change

int64_t omega_change_get_transform_computed_file_size_after(const omega_change_t *change_ptr)

Given a transform change, return the computed file size after the transform.

Parameters:: change_ptr – transform change to inspect
Returns:: computed file size after the transform, or -1 if this is not a transform change

int omega_change_is_undone(const omega_change_t *change_ptr)

Given a change, determine if this change is undone

Parameters:: change_ptr – change to determine if it has been undone or not
Returns:: non-zero if the change is undone, and zero otherwise

check.h

Function to assert the integrity of the internal editing model.

Functions

int omega_check_model(const omega_session_t *session_ptr)

Checks the internal session model for errors

Parameters:: session_ptr – session whose model to check for errors
Returns:: 0 if the model is error free and non-zero otherwise

config.h

Configuration settings.

Defines

O_BINARY

OMEGA_VIEWPORT_CAPACITY_LIMIT: Define to enable debugging Default maximum viewport capacity

OMEGA_SEARCH_PATTERN_LENGTH_LIMIT: Define the maximum length of a pattern for searching

OMEGA_MEMORY_BUFFER_LIMIT: Maximum byte range that APIs may materialize into one in-memory buffer.

OMEGA_REPLACE_MATCHES_LIMIT: Maximum selected matches that transactional replace-matches may materialize into one in-memory script.

OMEGA_CHANGE_INLINE_PAYLOAD_LIMIT: Maximum primitive payload byte range stored inline before using file-backed storage.

OMEGA_BYTE_T: Define the byte type to be used across the project

OMEGA_BUILD_UNIX: Define if building for Unix-like operating systems

OMEGA_BUILD_64_BIT: Define if building for 64-bit

ATTRIBUTE_UNUSED

OPEN: Alias for the open function, accommodating large files if _LARGEFILE_SOURCE is defined.

FOPEN: Alias for the fopen function used to open a file pointer.

FCLOSE: Alias for the fclose function used to close a file pointer.

CLOSE: Alias for the close function used to close a file descriptor.

FSEEK: Alias for the fseek/fseeko function, using a 64-bit file offset API where needed to accommodate large files.

FTELL: Alias for the ftell/ftello function, using a 64-bit file offset API where needed to accommodate large files.

Functions

static inline int safe_open_(const char *filename, int oflag, int pmode)

static inline FILE *safe_fopen_(const char *filename, const char *mode)

Function to safely open a file pointer, using fopen_s where supported.

Parameters:

filename – file name to open
mode – mode to open the file in

Returns:

opened file pointer

edit.h

Main editing functions.

Typedefs

typedef int (*omega_edit_overwrite_guard_cbk_t)(const char *file_path, void *user_data_ptr)

Callback used to verify an overwrite target immediately before core publishes a saved file.

The callback is invoked only when the target is the session’s original file and core detects that it changed since the last synchronization. Return zero to allow the overwrite or non-zero to preserve the target and report ORIGINAL_MODIFIED. Core does not lock the target across this callback and the following atomic replacement, so the callback detects conflicts but cannot provide transactional compare-and-swap semantics against concurrent writers.

Enums

enum omega_edit_script_op_kind_t

Batch script operation kinds for sequential edit replay.

Values:

enumerator OMEGA_EDIT_SCRIPT_DELETE

enumerator OMEGA_EDIT_SCRIPT_INSERT

enumerator OMEGA_EDIT_SCRIPT_OVERWRITE

enumerator OMEGA_EDIT_SCRIPT_REPLACE

enum omega_edit_transform_kind_t

Built-in byte transform kinds.

Values:

enumerator OMEGA_EDIT_TRANSFORM_ASCII_TO_UPPER

enumerator OMEGA_EDIT_TRANSFORM_ASCII_TO_LOWER

enumerator OMEGA_EDIT_TRANSFORM_BITWISE_AND

enumerator OMEGA_EDIT_TRANSFORM_BITWISE_OR

enumerator OMEGA_EDIT_TRANSFORM_BITWISE_XOR

Functions

omega_session_t *omega_edit_create_session(const char *file_path, omega_session_event_cbk_t cbk, void *user_data_ptr, int32_t event_interest, const char *checkpoint_directory)

Create a file editing session from a file path

Parameters:

file_path – file path, will be opened for read, to create an editing session with, or nullptr if starting from scratch
cbk – user-defined callback function called whenever a content affecting change is made to this session
user_data_ptr – pointer to user-defined data to associate with this session
event_interest – oring together the session events of interest, or zero if all session events are desired
checkpoint_directory – directory to store checkpoints in, if null, then it will try to use the same directory as the file_path, and if that fails, then it will use the system temp directory, and if that fails, it will use the current working directory

Returns:

pointer to the created session, or NULL on failure

omega_session_t *omega_edit_create_session_from_bytes(const omega_byte_t *data_ptr, int64_t length, omega_session_event_cbk_t cbk, void *user_data_ptr, int32_t event_interest, const char *checkpoint_directory)

Create an editing session backed by an in-memory byte buffer.

Parameters:

data_ptr – bytes to seed the session with, or nullptr if length is zero
length – number of bytes in data_ptr
cbk – user-defined callback function called whenever a content affecting change is made to this session
user_data_ptr – pointer to user-defined data to associate with this session
event_interest – oring together the session events of interest, or zero if all session events are desired
checkpoint_directory – directory to store checkpoints in, if null, the system temp directory (or current working directory as a last resort) will be used. A checkpoint file is still created internally so the session can reuse the standard file-backed model and checkpoint machinery.

Returns:

pointer to the created session, or NULL on failure

void omega_edit_destroy_session(omega_session_t *session_ptr)

Destroy the given session and all associated objects (changes, and viewports)

Parameters:: session_ptr – session to destroy

omega_viewport_t *omega_edit_create_viewport(omega_session_t *session_ptr, int64_t offset, int64_t capacity, int is_floating, omega_viewport_event_cbk_t cbk, void *user_data_ptr, int32_t event_interest)

Create a new viewport, returns a pointer to the new viewport

Parameters:

session_ptr – session to create the new viewport in
offset – offset for the new viewport
capacity – desired capacity of the new viewport
is_floating – 0 if the viewport is to remain fixed at the given offset, non-zero if the viewport is expected to “float” as bytes are inserted or deleted before the start of this viewport
cbk – user-defined callback function called whenever the viewport gets updated
user_data_ptr – pointer to user-defined data to associate with this new viewport
event_interest – oring together the viewport events of interest, or zero if all viewport events are desired

Returns:

pointer to the new viewport, or NULL on failure

omega_viewport_t *omega_edit_create_viewport_with_options(omega_session_t *session_ptr, const omega_edit_viewport_options_t *options)

Create a new viewport using a named options structure.

Parameters:

session_ptr – session to create the new viewport in
options – viewport creation options

Returns:

pointer to the new viewport, or NULL on failure

void omega_edit_destroy_viewport(omega_viewport_t *viewport_ptr)

Destroy a given viewport

Parameters:: viewport_ptr – viewport to destroy

int omega_edit_clear_changes(omega_session_t *session_ptr)

Given a session, clear all active changes

Parameters:: session_ptr – session to clear all changes for
Returns:: zero on success and non-zero otherwise

int omega_edit_restore_to_change_count(omega_session_t *session_ptr, int64_t change_count)

Restore a session to a previous active change count and discard redo history. The target count must be between the current model’s available history base and the current active change count. Checkpoint-backed transform models created after the target count are discarded.

Parameters:

session_ptr – session to restore
change_count – active change count to keep

Returns:

zero on success and non-zero otherwise

int64_t omega_edit_undo_last_change(omega_session_t *session_ptr)

Given a session, undo the last change

Parameters:: session_ptr – session to undo the last change for
Returns:: negative serial number of the undone change if successful, zero otherwise

int64_t omega_edit_redo_last_undo(omega_session_t *session_ptr)

Redoes the last undo (if available)

Parameters:: session_ptr – session to redo the last undo for
Returns:: positive serial number of the redone change if successful, zero otherwise

int omega_edit_serial_result_is_success(int64_t result)

Test a serial-returning edit result, such as omega_edit_insert or omega_edit_delete, for success.

Parameters:: result – edit result value
Returns:: non-zero when result is a positive change serial

int omega_edit_status_result_is_success(int result)

Test a status-returning edit result, such as omega_edit_clear_changes or omega_edit_apply_script, for success.

Parameters:: result – edit status value
Returns:: non-zero when result is zero

int omega_edit_save_segment_with_options(omega_session_t *session_ptr, const char *file_path, int io_flags, char *saved_file_path, int64_t offset, int64_t length, const omega_edit_save_options_t *options_ptr)

Save a segment with an optional native overwrite guard.

This is equivalent to omega_edit_save_segment when options_ptr is null. A configured overwrite guard is evaluated at the final publish boundary only when core’s normal original-file modification check detects a conflict.

int omega_edit_save_segment(omega_session_t *session_ptr, const char *file_path, int io_flags, char *saved_file_path, int64_t offset, int64_t length)

Save a segment of the the given session (the edited file) to the given file path. If the save file already exists, it can be overwritten if overwrite is non zero. If the file exists and overwrite is zero, a new unique file name will be used as determined by omega_util_available_filename. If the file being edited is overwritten, the affected editing session will be reset.

Parameters:

session_ptr – session to save
file_path – file path to save to
io_flags – save IO flags (see omega_io_flags_t for details)
saved_file_path – if overwrite is not set and the target file_path exists, a new file path will be created, and if this parameter is non-null, the saved file path will be copied here (must be able to accommodate FILENAME_MAX bytes)
offset – save starting at this offset in the session
length – save this many bytes from the given start offset

Returns:

0 on success, non-zero otherwise

int omega_edit_save(omega_session_t *session_ptr, const char *file_path, int io_flags, char *saved_file_path)

Save the given session (the edited file) to the given file path. If the save file already exists, it can be overwritten if overwrite is non zero. If the file exists and overwrite is zero, a new unique file name will be used as determined by omega_util_available_filename. If the file being edited is overwritten, the affected editing session will be reset.

Parameters:

session_ptr – session to save
file_path – file path to save to
io_flags – save IO flags (see omega_io_flags_t for details)
saved_file_path – if overwrite is not set and the target file_path exists, a new file path will be created, and if this parameter is non-null, the saved file path will be copied here (must be able to accommodate FILENAME_MAX bytes)

Returns:

0 on success, non-zero otherwise

int omega_edit_save_with_options(omega_session_t *session_ptr, const char *file_path, int io_flags, char *saved_file_path, const omega_edit_save_options_t *options_ptr): Save a complete session with an optional native overwrite guard.

int omega_edit_save_segment_to_file(const omega_session_t *session_ptr, FILE *file_ptr, int64_t offset, int64_t length)

Write a session byte range to an already-open file without publishing a save event.

The caller owns file_ptr and is responsible for closing it. The file is flushed before this function returns. The session model is not modified.

Parameters:

session_ptr – session to copy from
file_ptr – already-open output file
offset – starting byte offset in the session
length – number of bytes to copy, or zero to copy from offset to the end of the session

Returns:

zero on success and non-zero otherwise

int omega_edit_save_segment_to_file_with_options(const omega_session_t *session_ptr, FILE *file_ptr, int64_t offset, int64_t length, const omega_edit_save_segment_to_file_options_t *options_ptr)

Write a session byte range to an already-open file without publishing a save event.

The caller owns file_ptr and is responsible for closing it. The file’s stdio buffers are flushed before this function returns. Unless options_ptr is non-null and skip_disk_sync is true, the file is also synced to disk. The session model is not modified.

Parameters:

session_ptr – session to copy from
file_ptr – already-open output file
offset – starting byte offset in the session
length – number of bytes to copy, or zero to copy from offset to the end of the session
options_ptr – optional write behavior controls

Returns:

zero on success and non-zero otherwise

int omega_edit_save_segment_to_bytes(const omega_session_t *session_ptr, omega_byte_t **data_ptr_out, int64_t *length_out, int64_t offset, int64_t length)

Copy a bounded session byte range into a newly allocated memory buffer.

Parameters:

session_ptr – session to copy from
data_ptr_out – receives a malloc-allocated buffer containing the copied bytes (caller must free). The buffer is null-terminated for convenience, but length_out reports the logical byte count.
length_out – receives the number of copied bytes
offset – starting byte offset in the session
length – number of bytes to copy, or zero to copy from offset to the end of the session

Returns:

0 on success, non-zero otherwise. Requests larger than OMEGA_MEMORY_BUFFER_LIMIT fail; use omega_edit_save_segment for large streaming exports.

int omega_edit_save_to_bytes(const omega_session_t *session_ptr, omega_byte_t **data_ptr_out, int64_t *length_out)

Copy the full computed session content into a newly allocated memory buffer when it is bounded.

Parameters:

session_ptr – session to copy from
data_ptr_out – receives a malloc-allocated buffer containing the copied bytes (caller must free). The buffer is null-terminated for convenience, but length_out reports the logical byte count.
length_out – receives the number of copied bytes

Returns:

0 on success, non-zero otherwise. Large sessions fail instead of attempting an unbounded allocation; use omega_edit_save for large streaming exports.

int64_t omega_edit_delete(omega_session_t *session_ptr, int64_t offset, int64_t length)

Delete a number of bytes at the given offset

Parameters:

session_ptr – session to make the change in
offset – location offset to make the change
length – number of bytes to delete

Returns:

positive change serial number on success, 0 when the request is rejected without error, or -1 for invalid arguments

int64_t omega_edit_insert_bytes(omega_session_t *session_ptr, int64_t offset, const omega_byte_t *bytes, int64_t length)

Insert a number of bytes at the given offset

Warning

This byte-oriented API never infers a length from strlen. Use omega_edit_insert for null-terminated C strings. Passing length 0 is treated as a no-op.

Parameters:

session_ptr – session to make the change in
offset – location offset to make the change
bytes – bytes to insert at the given offset
length – explicit number of bytes to insert

Returns:

positive change serial number on success, 0 for a no-op when length is 0 or when the request is rejected without error, or -1 for invalid arguments

int64_t omega_edit_insert(omega_session_t *session_ptr, int64_t offset, const char *cstr, int64_t length)

Insert a C string at the given offset

Warning

This helper is for null-terminated text inputs. For binary data or buffers that may contain embedded nulls, use omega_edit_insert_bytes and pass an explicit byte length.

Parameters:

session_ptr – session to make the change in
offset – location offset to make the change
cstr – C string to insert at the given offset
length – length of the C string to insert (if 0, strlen will be used to calculate the length of null-terminated bytes)

Returns:

positive change serial number on success, 0 when the request is rejected without error, or -1 for invalid arguments

int64_t omega_edit_insert_cstring(omega_session_t *session_ptr, int64_t offset, const char *cstr)

Insert a null-terminated C string at the given offset.

This is the explicit inferred-length text variant. Binary callers should use omega_edit_insert_bytes.

int64_t omega_edit_overwrite_bytes(omega_session_t *session_ptr, int64_t offset, const omega_byte_t *bytes, int64_t length)

Overwrite bytes at the given offset with the given new bytes

Warning

This byte-oriented API never infers a length from strlen. Use omega_edit_overwrite for null-terminated C strings. Passing length 0 is treated as a no-op.

Parameters:

session_ptr – session to make the change in
offset – location offset to make the change
bytes – new bytes to overwrite the old bytes with
length – explicit number of new bytes

Returns:

positive change serial number on success, 0 for a no-op when length is 0 or when the request is rejected without error, or -1 for invalid arguments

int64_t omega_edit_overwrite(omega_session_t *session_ptr, int64_t offset, const char *cstr, int64_t length)

Overwrite bytes at the given offset with the given new C string

Warning

This helper is for null-terminated text inputs. For binary data or buffers that may contain embedded nulls, use omega_edit_overwrite_bytes and pass an explicit byte length.

Parameters:

session_ptr – session to make the change in
offset – location offset to make the change
cstr – new C string to overwrite the old bytes with
length – length of the new C string (if 0, strlen will be used to calculate the length of null-terminated bytes)

Returns:

positive change serial number on success, 0 when the request is rejected without error, or -1 for invalid arguments

int64_t omega_edit_overwrite_cstring(omega_session_t *session_ptr, int64_t offset, const char *cstr)

Overwrite bytes at the given offset with a null-terminated C string.

This is the explicit inferred-length text variant. Binary callers should use omega_edit_overwrite_bytes.

int64_t omega_edit_replace_bytes(omega_session_t *session_ptr, int64_t offset, int64_t delete_length, const omega_byte_t *bytes, int64_t insert_length)

Replace a span of bytes at the given offset with a new byte sequence.

If the delete and insert lengths match, this is lowered to a single overwrite. Otherwise it is applied as a delete followed by an insert in one logical transaction. If the insert step fails after a successful delete, the helper attempts to undo the delete before returning failure.

Parameters:

session_ptr – session to make the change in
offset – location offset to make the change
delete_length – number of original bytes to remove
bytes – replacement bytes, or null if insert_length is zero
insert_length – explicit number of replacement bytes to insert

Returns:

positive change serial number on success; 0 if the request is rejected without error or results in no change; -1 if the arguments are invalid (for example, session_ptr is null or bytes is null while insert_length is greater than zero)

int omega_edit_replace_bytes_checkpointed(omega_session_t *session_ptr, int64_t offset, int64_t delete_length, const omega_byte_t *bytes, int64_t insert_length)

Replace a span of bytes by streaming the resulting session into a new checkpoint.

This avoids storing replacement bytes in memory-backed change history and is intended for large generated replacements. Like other checkpoint operations, it promotes the newly written checkpoint as the active model.

Parameters:

session_ptr – session to make the change in
offset – location offset to make the change
delete_length – number of original bytes to remove
bytes – replacement bytes, or null if insert_length is zero
insert_length – explicit number of replacement bytes to insert

Returns:

zero on success and non-zero otherwise

int64_t omega_edit_replace_bytes_as_transform(omega_session_t *session_ptr, int64_t offset, int64_t delete_length, const omega_byte_t *bytes, int64_t insert_length, const char *transform_id, const char *options_json)

Materialize a transform result through a checkpoint-backed model and record a lightweight transform change.

The replacement bytes are written into the checkpoint and are not retained in the change log. The returned serial identifies a transform entry with the transform id, options JSON, affected range, replacement length, and computed file sizes.

Parameters:

session_ptr – session to make the change in
offset – location offset to make the change
delete_length – number of original bytes to remove
bytes – replacement bytes, or null if insert_length is zero
insert_length – explicit number of replacement bytes to insert
transform_id – stable transform identifier
options_json – optional transform options JSON

Returns:

positive transform change serial if successful, non-positive otherwise

int64_t omega_edit_replace(omega_session_t *session_ptr, int64_t offset, int64_t delete_length, const char *cstr, int64_t insert_length)

Replace a span of bytes at the given offset with a new C string.

Parameters:

session_ptr – session to make the change in
offset – location offset to make the change
delete_length – number of original bytes to remove
cstr – replacement C string, or null if insert_length is zero
insert_length – length of the replacement string (if 0, strlen will be used for null-terminated text)

Returns:

positive change serial number on success; 0 if the request is rejected without error or results in no change; -1 if the arguments are invalid (for example, session_ptr is null, a length is negative, or cstr is null while insert_length is greater than zero)

int64_t omega_edit_replace_cstring(omega_session_t *session_ptr, int64_t offset, int64_t delete_length, const char *cstr)

Replace a span of bytes at the given offset with a null-terminated C string.

This is the explicit inferred-length text variant. Binary callers should use omega_edit_replace_bytes.

int omega_edit_replace_matches_bytes(omega_session_t *session_ptr, const omega_byte_t *pattern, int64_t pattern_length, const omega_byte_t *replacement, int64_t replacement_length, omega_search_case_folding_t case_folding, int is_reverse, int64_t offset, int64_t length, int64_t limit, int front_to_back, int overwrite_only, int64_t *replacement_count_out, int64_t *delete_count_out, int64_t *insert_count_out, int64_t *overwrite_count_out)

Replace matching byte patterns inside a session range using in-place transactional edits.

Matches are located against the original session content and replaced in one logical transaction. Matching is non-overlapping: after a match is found, searching resumes immediately after the matched pattern bytes in the original content. When front_to_back is non-zero, replacements are applied from the start of the range toward the end with offset adjustments for prior replacements. When front_to_back is zero, replacements are applied from the end toward the start so no offset adjustment is required.

Each individual match is lowered through the same optimized edit shape used by higher-level clients: unchanged prefix/suffix bytes are trimmed so a match may become an insert, delete, overwrite, or replace op depending on the actual delta. When overwrite_only is non-zero, each match is applied as a raw overwrite of the replacement bytes at the match offset without deleting any extra bytes from the matched pattern.

Parameters:

session_ptr – session to edit
pattern – pattern bytes to search for
pattern_length – explicit number of bytes in pattern
replacement – replacement bytes, or null if replacement_length is zero
replacement_length – explicit number of bytes in replacement
case_folding – case folding mode; use OMEGA_SEARCH_CASE_FOLDING_NONE for exact byte matching
is_reverse – zero to search forward and non-zero to search backward before applying replacements
offset – starting byte offset of the replace range
length – number of bytes in the replace range, or zero to search from offset to end of session
limit – maximum number of matches to replace, or zero for no caller-specified limit. The transactional replace path still refuses to materialize more than OMEGA_REPLACE_MATCHES_LIMIT selected matches, further bounded by OMEGA_MEMORY_BUFFER_LIMIT; use omega_edit_replace_all_bytes for streamed large replace-all work.
front_to_back – non-zero to apply replacements from low offsets to high offsets, zero for high-to-low
overwrite_only – non-zero to overwrite replacement bytes in place instead of replacing the full matched span
replacement_count_out – optional out-parameter that receives the number of matches selected for replacement
delete_count_out – optional out-parameter that receives the number of lowered delete operations
insert_count_out – optional out-parameter that receives the number of lowered insert operations
overwrite_count_out – optional out-parameter that receives the number of lowered overwrite operations

Returns:

zero on success and non-zero otherwise

int omega_edit_replace_matches_bytes_with_options(omega_session_t *session_ptr, const omega_byte_t *pattern, int64_t pattern_length, const omega_byte_t *replacement, int64_t replacement_length, const omega_edit_replace_matches_options_t *options)

Replace matching byte patterns using named options.

Parameters:

session_ptr – session to edit
pattern – pattern bytes to search for
pattern_length – explicit number of bytes in pattern
replacement – replacement bytes, or null if replacement_length is zero
replacement_length – explicit number of bytes in replacement
options – named replace options

Returns:

zero on success and non-zero otherwise

int omega_edit_replace_matches(omega_session_t *session_ptr, const char *pattern, int64_t pattern_length, const char *replacement, int64_t replacement_length, omega_search_case_folding_t case_folding, int is_reverse, int64_t offset, int64_t length, int64_t limit, int front_to_back, int overwrite_only, int64_t *replacement_count_out, int64_t *delete_count_out, int64_t *insert_count_out, int64_t *overwrite_count_out)

Replace matching C-string patterns inside a session range using in-place transactional edits.

Parameters:

session_ptr – session to edit
pattern – pattern C string to search for
pattern_length – explicit pattern length (if 0, strlen will be used)
replacement – replacement C string, or null if replacement_length is zero
replacement_length – explicit replacement length (if 0, strlen will be used)
case_folding – case folding mode; use OMEGA_SEARCH_CASE_FOLDING_NONE for exact byte matching
is_reverse – zero to search forward and non-zero to search backward before applying replacements
offset – starting byte offset of the replace range
length – number of bytes in the replace range, or zero to search from offset to end of session
limit – maximum number of matches to replace, or zero for no caller-specified limit. The transactional replace path still refuses to materialize more than OMEGA_REPLACE_MATCHES_LIMIT selected matches, further bounded by OMEGA_MEMORY_BUFFER_LIMIT; use omega_edit_replace_all for streamed large replace-all work.
front_to_back – non-zero to apply replacements from low offsets to high offsets, zero for high-to-low
overwrite_only – non-zero to overwrite replacement bytes in place instead of replacing the full matched span
replacement_count_out – optional out-parameter that receives the number of matches selected for replacement
delete_count_out – optional out-parameter that receives the number of lowered delete operations
insert_count_out – optional out-parameter that receives the number of lowered insert operations
overwrite_count_out – optional out-parameter that receives the number of lowered overwrite operations

Returns:

zero on success and non-zero otherwise

int omega_edit_replace_matches_with_options(omega_session_t *session_ptr, const char *pattern, int64_t pattern_length, const char *replacement, int64_t replacement_length, const omega_edit_replace_matches_options_t *options): Replace matching C-string patterns using named options.

int omega_edit_replace_all_bytes(omega_session_t *session_ptr, const omega_byte_t *pattern, int64_t pattern_length, const omega_byte_t *replacement, int64_t replacement_length, omega_search_case_folding_t case_folding, int64_t offset, int64_t length, int64_t *replacement_count_out)

Replace all non-overlapping matches of a byte pattern within a session range using a streamed checkpoint rewrite.

The current session content is read once in forward order and rewritten into a new checkpoint file. Bytes outside the target range are copied through unchanged; bytes inside the range are copied unchanged except where they match the pattern, in which case the replacement bytes are written instead. Matching is performed against the original session bytes, not against already-written replacement output.

If no matches are found, the session is left unchanged and replacement_count_out receives 0. If matches are found, the newly written checkpoint becomes the active model and the session emits the same checkpoint/transform notifications used by omega_edit_apply_transform.

Warning

Matches are replaced in forward order and are non-overlapping. After a match is consumed, searching resumes immediately after the matched bytes in the original session content.

Warning

This byte-oriented API never infers a length from strlen. Use omega_edit_replace_all for null-terminated C strings.

Parameters:

session_ptr – session to edit
pattern – pattern bytes to search for
pattern_length – explicit number of bytes in pattern
replacement – replacement bytes, or null if replacement_length is zero
replacement_length – explicit number of bytes in replacement
case_folding – case folding mode; use OMEGA_SEARCH_CASE_FOLDING_NONE for exact byte matching
offset – starting byte offset of the replace-all range
length – number of bytes in the replace-all range, or zero to search from offset to end of session
replacement_count_out – optional out-parameter that receives the number of replacements performed

Returns:

zero on success and non-zero otherwise

int omega_edit_replace_all_bytes_directional(omega_session_t *session_ptr, const omega_byte_t *pattern, int64_t pattern_length, const omega_byte_t *replacement, int64_t replacement_length, omega_search_case_folding_t case_folding, int is_reverse, int64_t offset, int64_t length, int64_t *replacement_count_out)

Replace all non-overlapping matches of a byte pattern using a streamed checkpoint rewrite and explicit search direction.

Forward replacement selects matches greedily from low offsets to high offsets. Reverse replacement selects matches greedily from high offsets to low offsets, preserving reverse-search overlap semantics without materializing every match offset.

Parameters:

session_ptr – session to edit
pattern – pattern bytes to search for
pattern_length – explicit number of bytes in pattern
replacement – replacement bytes, or null if replacement_length is zero
replacement_length – explicit number of bytes in replacement
case_folding – case folding mode; use OMEGA_SEARCH_CASE_FOLDING_NONE for exact byte matching
is_reverse – zero to select matches forward and non-zero to select matches backward
offset – starting byte offset of the replace range
length – number of bytes in the replace range, or zero to search from offset to end of session
replacement_count_out – optional out-parameter that receives the number of replacements performed

Returns:

zero on success and non-zero otherwise

int omega_edit_replace_all_bytes_with_options(omega_session_t *session_ptr, const omega_byte_t *pattern, int64_t pattern_length, const omega_byte_t *replacement, int64_t replacement_length, const omega_edit_replace_all_options_t *options): Replace all non-overlapping matches of a byte pattern using named options.

int omega_edit_replace_all(omega_session_t *session_ptr, const char *pattern, int64_t pattern_length, const char *replacement, int64_t replacement_length, omega_search_case_folding_t case_folding, int64_t offset, int64_t length, int64_t *replacement_count_out)

Replace all non-overlapping matches of a C-string pattern within a session range using a streamed checkpoint rewrite.

Warning

This helper is for null-terminated text inputs. For binary data or buffers that may contain embedded nulls, use omega_edit_replace_all_bytes and pass explicit byte lengths.

Parameters:

session_ptr – session to edit
pattern – pattern C string to search for
pattern_length – length of the pattern string (if 0, strlen will be used for null-terminated text)
replacement – replacement C string, or null if replacement_length is zero
replacement_length – length of the replacement string (if 0, strlen will be used for null-terminated text)
case_folding – case folding mode; use OMEGA_SEARCH_CASE_FOLDING_NONE for exact byte matching
offset – starting byte offset of the replace-all range
length – number of bytes in the replace-all range, or zero to search from offset to end of session
replacement_count_out – optional out-parameter that receives the number of replacements performed

Returns:

zero on success and non-zero otherwise

int omega_edit_replace_all_with_options(omega_session_t *session_ptr, const char *pattern, int64_t pattern_length, const char *replacement, int64_t replacement_length, const omega_edit_replace_all_options_t *options): Replace all non-overlapping C-string matches using named options.

int omega_edit_replace_all_cstring(omega_session_t *session_ptr, const char *pattern, const char *replacement, omega_search_case_folding_t case_folding, int64_t offset, int64_t length, int64_t *replacement_count_out)

Replace all non-overlapping matches of a null-terminated C-string pattern with a null-terminated C string.

This is the explicit inferred-length text variant. Binary callers should use omega_edit_replace_all_bytes.

int omega_edit_apply_script(omega_session_t *session_ptr, const omega_edit_script_op_t *ops, size_t op_count)

Apply an array of edit script operations sequentially to the given session.

Operations are applied in the order given. The function does not roll back already-applied operations if a later operation fails; it simply stops and returns non-zero.

Parameters:

session_ptr – session to edit
ops – array of edit operations
op_count – number of operations in the array

Returns:

zero on success and non-zero otherwise

int omega_edit_apply_builtin_transform(omega_session_t *session_ptr, omega_edit_transform_t transform, int64_t offset, int64_t length)

Checkpoint and apply a built-in transform to bytes starting at the given offset up to the given length.

This is a stable C API layer for common transform operations that higher-level clients and services can expose without requiring process-local callback functions. Use omega_edit_apply_transform for custom callback transforms.

Parameters:

session_ptr – session to transform
transform – built-in transform descriptor
offset – location offset to begin transforming bytes
length – number of bytes from the given offset to transform, or zero to transform through the end of session

Returns:

zero on success, non-zero otherwise

int omega_edit_apply_transform(omega_session_t *session_ptr, omega_util_byte_transform_t transform, void *user_data_ptr, int64_t offset, int64_t length)

Checkpoint and apply the given mask of the given mask type to the bytes starting at the given offset up to the given length

Parameters:

session_ptr – session to make the change in
transform – byte transform to apply
user_data_ptr – pointer to user data that will be sent through to the given transform
offset – location offset to make the change
length – the number of bytes from the given offset to apply the mask to

Returns:

zero on success, non-zero otherwise

int omega_edit_create_checkpoint(omega_session_t *session_ptr)

Creates a session checkpoint.

Parameters:: session_ptr – session to checkpoint
Returns:: zero on success, non-zero otherwise

int omega_edit_destroy_last_checkpoint(omega_session_t *session_ptr)

Destroys the last checkpoint created on the given session

Parameters:: session_ptr – session to remove the checkpoint
Returns:: zero on success, non-zero otherwise

int omega_edit_checkout_checkpoint(omega_session_t *session_ptr, int64_t checkpoint_count)

Moves the session to a checkpoint boundary without destroying later checkpoint models.

Checkpoint zero is the original session snapshot. Later checkpoints remain available for a subsequent checkout until a successful edit creates a new branch or omega_edit_discard_checkpoint_future is called.

Parameters:

session_ptr – session to navigate
checkpoint_count – checkpoint boundary to make active, from zero through the active plus future checkpoint count

Returns:

zero on success, non-zero otherwise

int64_t omega_edit_discard_checkpoint_future(omega_session_t *session_ptr)

Permanently destroys all checkpoint models after the active checkpoint boundary.

Parameters:: session_ptr – session whose future checkpoint branch should be discarded
Returns:: number of discarded future checkpoints, or a negative value on error

int omega_edit_restore_last_checkpoint(omega_session_t *session_ptr)

Restores the current session content to the most recent checkpoint snapshot.

Unlike omega_edit_destroy_last_checkpoint, this keeps the checkpoint model in place and discards only the edits made after that checkpoint snapshot.

Parameters:: session_ptr – session to restore
Returns:: zero on success, non-zero otherwise

struct omega_edit_viewport_options_t

#include <edit.h>

Options for creating a viewport with named fields.

Public Members

int64_t offset

int64_t capacity

omega_edit_bool_t is_floating

omega_viewport_event_cbk_t cbk

void *user_data_ptr

int32_t event_interest

struct omega_edit_save_options_t

#include <edit.h>

Optional behavior for publishing a session save.

Public Members

omega_edit_overwrite_guard_cbk_t overwrite_guard

void *overwrite_guard_user_data

struct omega_edit_save_segment_to_file_options_t

#include <edit.h>

Options for writing a session byte range to an already-open file.

Public Members

omega_edit_bool_t skip_disk_sync: Flush stdio buffers only; skip the OS-level disk sync for short-lived temporary snapshots.

struct omega_edit_script_op_t

#include <edit.h>

A single edit script operation.

Semantics by kind:

DELETE: remove length bytes at offset; bytes and bytes_length are ignored
INSERT: insert bytes_length bytes from bytes at offset; length should be 0
OVERWRITE: overwrite length bytes at offset with bytes_length bytes from bytes (length and bytes_length should match when both are non-zero)
REPLACE: replace length bytes at offset with bytes_length bytes from bytes

Public Members

int64_t offset

int64_t length

omega_edit_script_op_kind_t kind

const omega_byte_t *bytes

int64_t bytes_length

struct omega_edit_transform_t

#include <edit.h>

A built-in byte transform description.

operand is used by bitwise transform kinds and ignored by ASCII case transform kinds.

Public Members

omega_edit_transform_kind_t kind

omega_byte_t operand

struct omega_edit_replace_matches_options_t

#include <edit.h>

Options for replacing matches with named fields.

Public Members

omega_search_case_folding_t case_folding

omega_edit_bool_t is_reverse

int64_t offset

int64_t length

int64_t limit

omega_edit_bool_t front_to_back

omega_edit_bool_t overwrite_only

int64_t *replacement_count_out

int64_t *delete_count_out

int64_t *insert_count_out

int64_t *overwrite_count_out

struct omega_edit_replace_all_options_t

#include <edit.h>

Options for streamed replace-all operations.

Public Members

omega_search_case_folding_t case_folding

omega_edit_bool_t is_reverse

int64_t offset

int64_t length

int64_t *replacement_count_out

encode.h

Encoding functions.

Functions

size_t omega_encode_bin2hex(const omega_byte_t *src, char *dst, size_t src_length)

Given a pointer to bytes, and a character pointer destination, write the hex values of the bytes to the destination

Parameters:

src – pointer to bytes
dst – destination, must be memory sufficient to hold (src_length * 2) + 1 bytes (will be null-terminated)
src_length – src_length of the bytes

Returns:

number of characters written to the destination, or 0 if unsuccessful

size_t omega_encode_hex2bin(const char *src, omega_byte_t *dst, size_t src_length)

Given a pointer to hex characters, write the binary representation to dst

Parameters:

src – pointer to hex characters
dst – destination, must be memory sufficient to hold (src_length / 2) + 1 bytes (will be null-terminated)
src_length – src_length of the hex characters

Returns:

number of bytes written to the destination, or 0 if unsuccessful

filesystem.h

Filesystem functions.

Functions

int omega_util_mkstemp(char *tmpl, int mode)

Generate a temporary file name based on tmpl. The name constructed does not exist at the time of the call. The tmpl parameter is overwritten with the result.

Parameters:

tmpl – must match the rules for mk[s]temp (i.e. end in “XXXXXX”)
mode – mode to set the file to, if zero then the mode is set to 0600 modulo umask

Returns:

read-write file descriptor opened with mode 0600 modulo umask or -1 with errno set on error

const char *omega_util_get_current_dir(char *buffer)

Gets the current working directory

Parameters:: buffer – pointer to memory to hold the current working directory (allocated to at least FILENAME_MAX) or could be NULL, in which case an internal static buffer will be used
Returns:: current working directory or NULL on error

int omega_util_file_exists(const char *file_name)

Check if the given file name exists

Parameters:: file_name – file name to check existence of
Returns:: non-zero if the file exists, and zero otherwise

int omega_util_directory_exists(const char *path)

Check if the given directory exists

Parameters:: path – directory to check for the existence of
Returns:: non-zero if the directory exists and zero otherwise

int omega_util_create_directory(char const *path)

Create the given directory

Parameters:: path – directory to create
Returns:: zero if the path was created successfully and non-zero otherwise

int omega_util_remove_file(char const *path)

Remove the given file

Parameters:: path – path to the fle to remove
Returns:: zero if the file was removed successfully and non-zero otherwise

int omega_util_remove_directory(char const *path)

Remove the given directory

Parameters:: path – directory to remove
Returns:: zero if the path was removed successfully and non-zero otherwise

uint64_t omega_util_remove_all(char const *path)

Remove the given path, whether it is a file or directory

Parameters:: path – directory or file to remove
Returns:: number of files removed

int64_t omega_util_file_size(char const *path)

Given a file path, return the file size

Parameters:: path – path to get the file size of
Returns:: file size, or -1 on error

int64_t omega_util_read_file_segment(char const *path, int64_t offset, void *buffer, int64_t byte_count)

Read a byte range from a regular file path into a caller-provided buffer.

Parameters:

path – path to read from
offset – non-negative byte offset to begin reading
buffer – destination buffer
byte_count – number of bytes to read

Returns:

bytes read, or -1 on error or short read

int omega_util_paths_equivalent(char const *path1, char const *path2)

Given two file paths, determine if they are equivalent

Parameters:

path1 – first path
path2 – second path

Returns:

non-zero if the paths are equivalent and zero otherwise, including on invalid or missing paths

int omega_util_compare_files(const char *path1, const char *path2)

Compare the contents of two files

Parameters:

path1 – first path
path2 – second path

Returns:

0 if the contents are equal, 1 if the contents are not equal, or -1 if an error occurred opening the file at path1 or -2 if an error occurred opening the file at path2

int omega_util_compare_modification_times(const char *path1, const char *path2)

Compare the modification times of two files

Parameters:

path1 – first path
path2 – second path

Returns:

0 if the modification times are equal, -1 if the modification time of path1 is less than path2, 1 if the modification time of path1 is greater than path2, or -2 if an error occurred

int omega_util_get_modification_time(const char *path, int64_t *modification_time_out)

Get a file modification time value that can be compared with later values from the same function

Parameters:

path – file path
modification_time_out – pointer to receive the modification time value

Returns:

0 on success, or a negative value on failure

char *omega_util_basename(char const *path, char *buffer, int drop_suffix)

Given a file name, return the associated basename (filename without the directory) and if a matching suffix is given, the returned basename will have the suffix removed

Parameters:

path – file path
buffer – pointer to memory to hold the base name (allocated to at least FILENAME_MAX) or could be NULL, in which case an internal static buffer will be used
drop_suffix – if non-zero, remove the suffix (file extension) from the path basename

Returns:

associated basename, possibly without the suffix

char *omega_util_file_extension(char const *path, char *buffer)

Given a file name, return the associated file extension, with or without the dot prefix

Parameters:

path – file path
buffer – pointer to memory to hold the file extension (allocated to at least FILENAME_MAX) or could be NULL, in which case an internal static buffer will be used

Returns:

associated file extension or NULL if no extension exists

char *omega_util_available_filename(char const *path, char *buffer)

Creates a available filename from the given path

Parameters:

path – desired path
buffer – pointer to a buffer that can hold up to FILENAME_MAX bytes, or NULL to use an internal static buffer

Returns:

a path that is currently available (insecure as the file may exist later at the time of attempted creation)

char *omega_util_normalize_path(char const *path, char *buffer)

Given a path, which must exist, returns an absolute path that has no symbolic link, dot, or dot-dot elements

Parameters:

path – path to get the absolute path of
buffer – pointer to memory to hold the file extension (allocated to at least FILENAME_MAX) or could be NULL, in which case an internal static buffer will be used

Returns:

absolute path that has no symbolic link, dot, or dot-dot path elements, or NULL on error

char *omega_util_dirname(char const *path, char *buffer)

Given a file name, return the associated directory

Parameters:

path – file path
buffer – pointer to memory to hold the directory name (allocated to at least FILENAME_MAX) or could be NULL, in which case an internal static buffer will be used

Returns:

associated directory

int omega_util_file_copy(const char *src_path, const char *dst_path, int mode)

Copy the file at the given source path to the given destination path

Parameters:

src_path – source path
dst_path – destination path
mode – mode to set the destination file to, if zero then the mode of the source file is used

Returns:

zero on success, non-zero on failure

char *omega_util_get_temp_directory()

Try to get the temporary directory for the host system

Returns:: temporary directory for the host system allocated by malloc (must be free’d by the caller), or NULL on error

int omega_util_touch(const char *file_name, int create)

Touch the given file, optionally creating it if it does not exist

Parameters:

file_name – flle name to touch
create – if non-zero, create the file name if it does not exist

Returns:

zero on success, non-zero on failure

char omega_util_directory_separator()

Returns the directory separator character used on the host system

Returns:: directory separator character used on the host system

fwd_defs.h

Forward definitions.

Defines

SESSION_EVENTS_ALL: Subscribe to all session events

VIEWPORT_EVENTS_ALL: Subscribe to all viewport events

ALL_EVENTS: Subscribe to all known events

NO_EVENTS: Subscribe to no events

ORIGINAL_MODIFIED: Error code to indicate that the original session file has been modified since the session was created

OMEGA_EDIT_REPLACE_ROLLBACK_FAILED: Replace failed after the delete step and the attempted rollback also failed; session content may have changed

OMEGA_EDIT_SAVE_DIRECTORY_SYNC_FAILED: Save data was published, but syncing the parent directory failed; contents may still be durable on the filesystem

Typedefs

typedef struct omega_character_counts_struct omega_character_counts_t: Opaque character counts

typedef struct omega_change_struct omega_change_t: Opaque change

typedef struct omega_search_context_struct omega_search_context_t: Opaque search context

typedef struct omega_segment_struct omega_segment_t: Opaque segment

typedef struct omega_session_struct omega_session_t: Opaque session

typedef struct omega_viewport_struct omega_viewport_t: Opaque viewport

typedef void (*omega_session_event_cbk_t)(const omega_session_t*, omega_session_event_t, const void*): On session change callback. This under-defined function will be called when a session event occurs.

typedef void (*omega_viewport_event_cbk_t)(const omega_viewport_t*, omega_viewport_event_t, const void*): On viewport change callback. This under-defined function will be called when an associated viewport event occurs.

Enums

enum omega_session_event_t

Enumeration of session events

Values:

enumerator SESSION_EVT_UNDEFINED

enumerator SESSION_EVT_CREATE

enumerator SESSION_EVT_EDIT

enumerator SESSION_EVT_UNDO

enumerator SESSION_EVT_CLEAR

enumerator SESSION_EVT_TRANSFORM

enumerator SESSION_EVT_CREATE_CHECKPOINT

enumerator SESSION_EVT_DESTROY_CHECKPOINT

enumerator SESSION_EVT_SAVE

enumerator SESSION_EVT_CHANGES_PAUSED

enumerator SESSION_EVT_CHANGES_RESUMED

enumerator SESSION_EVT_CREATE_VIEWPORT

enumerator SESSION_EVT_DESTROY_VIEWPORT

enumerator SESSION_EVT_TRANSACTION_STARTED

enumerator SESSION_EVT_TRANSACTION_ENDED

enumerator SESSION_EVT_TRANSFORM_STARTED

enumerator SESSION_EVT_TRANSFORM_PROGRESS

enumerator SESSION_EVT_TRANSFORM_COMPLETED

enumerator SESSION_EVT_TRANSFORM_FAILED

enumerator SESSION_EVT_RESTORE_CHECKPOINT

enum omega_viewport_event_t

Enumeration of viewport events

Values:

enumerator VIEWPORT_EVT_UNDEFINED

enumerator VIEWPORT_EVT_CREATE

enumerator VIEWPORT_EVT_EDIT

enumerator VIEWPORT_EVT_UNDO

enumerator VIEWPORT_EVT_CLEAR

enumerator VIEWPORT_EVT_TRANSFORM

enumerator VIEWPORT_EVT_MODIFY

enumerator VIEWPORT_EVT_CHANGES

enum omega_io_flags_t

Enumeration of IO flags

Values:

enumerator IO_FLG_NONE

enumerator IO_FLG_OVERWRITE

enumerator IO_FLG_FORCE_OVERWRITE

enum omega_edit_bool_t

Boolean-like option value used by options-struct APIs

Values:

enumerator OMEGA_EDIT_FALSE

enumerator OMEGA_EDIT_TRUE

enum omega_mask_kind_t

Mask types

Values:

enumerator MASK_AND

enumerator MASK_OR

enumerator MASK_XOR

enum omega_bom_t

Byte order mark (BOM) types

Values:

enumerator BOM_UNKNOWN

enumerator BOM_NONE

enumerator BOM_UTF8

enumerator BOM_UTF16LE

enumerator BOM_UTF16BE

enumerator BOM_UTF32LE

enumerator BOM_UTF32BE

license.h

Function to get the license text associated with omega-edit.

Functions

const char *omega_license_get()

Gets the license text

Returns:: null-terminated license text

scoped_ptr.hpp

Define a scoped smart pointer that can be used for Resource Acquisition Is Initialization (RAII) in C++ code.

search.h

Functions that enable searching within an editing session.

Enums

enum omega_search_case_folding_t

Single-byte case folding mode used when byte search compares text.

The byte model remains unchanged. OMEGA_SEARCH_CASE_FOLDING_NONE performs exact byte matching. Other enum values control the one-byte-to-one-byte lowercase transform applied to the search pattern and candidate bytes.

Values:

enumerator OMEGA_SEARCH_CASE_FOLDING_NONE

enumerator OMEGA_SEARCH_CASE_FOLDING_ASCII

enumerator OMEGA_SEARCH_CASE_FOLDING_WINDOWS_1252

enumerator OMEGA_SEARCH_CASE_FOLDING_CP437

enumerator OMEGA_SEARCH_CASE_FOLDING_EBCDIC_037

enumerator OMEGA_SEARCH_CASE_FOLDING_MAC_ROMAN

Functions

omega_search_context_t *omega_search_create_context_bytes(omega_session_t *session_ptr, const omega_byte_t *pattern, int64_t pattern_length, int64_t session_offset, int64_t session_length, omega_search_case_folding_t case_folding, int is_reverse_search)

Create a search context

Warning

This byte-oriented API never infers a pattern length from strlen. Use omega_search_create_context for null-terminated C strings. Passing pattern_length 0 is invalid and returns null.

Warning

Ensure that the pattern_length does not exceed the session_length - session_offset. This is considered an error and a null pointer will be returned.

Parameters:

session_ptr – session to find patterns in
pattern – pointer to the pattern to find (as a sequence of bytes)
pattern_length – explicit length of the pattern in bytes
session_offset – start searching at this offset within the session
session_length – search from the starting offset within the session up to this many bytes, if set to zero, it will track the computed session length
case_folding – case folding mode; use OMEGA_SEARCH_CASE_FOLDING_NONE for exact byte matching
is_reverse_search – zero for forward search and non-zero for reverse search

Returns:

search context

omega_search_context_t *omega_search_create_context(omega_session_t *session_ptr, const char *pattern, int64_t pattern_length, int64_t session_offset, int64_t session_length, omega_search_case_folding_t case_folding, int is_reverse_search)

Create a search context

Warning

This helper is for null-terminated text patterns. For binary data or patterns that may contain embedded nulls, use omega_search_create_context_bytes and pass an explicit pattern_length.

Warning

Ensure that the pattern_length does not exceed the session_length - session_offset. This is considered an error and a null pointer will be returned.

Parameters:

session_ptr – session to find the pattern in
pattern – pointer to the pattern to find (as a C string)
pattern_length – length of the pattern (if 0, strlen will be used to calculate the length of null-terminated bytes)
session_offset – start searching at this offset within the session
session_length – search from the starting offset within the session up to this many bytes, if set to zero, it will search to the end of the session
case_folding – case folding mode; use OMEGA_SEARCH_CASE_FOLDING_NONE for exact byte matching
is_reverse_search – zero for forward search and non-zero for reverse search

Returns:

search context

int omega_search_context_is_reverse_search(const omega_search_context_t *search_context_ptr)

Given a search context, determine if the search is being done forwards or backwards

Parameters:: search_context_ptr – search context to determine if the search is forwards or backwards
Returns:: zero for forwards search and non-zero for backwards search

int64_t omega_search_context_get_session_length(const omega_search_context_t *search_context_ptr)

Given a search context, return the session length

Parameters:: search_context_ptr – search context to get the session length from
Returns:: session length

int64_t omega_search_context_get_session_offset(const omega_search_context_t *search_context_ptr)

Given a search context, return the session offset

Parameters:: search_context_ptr – search context to get the session offset from
Returns:: session offset

int64_t omega_search_context_get_match_offset(const omega_search_context_t *search_context_ptr)

Given a search context, get the most recent search offset

Parameters:: search_context_ptr – search context to get the most recent search offset from
Returns:: most recent search offset, if the search offset is equal to the session length, then no match was found

int64_t omega_search_context_get_pattern_length(const omega_search_context_t *search_context_ptr)

Given a search context, get the pattern length

Parameters:: search_context_ptr – search context to get the pattern length from
Returns:: pattern length offset

int omega_search_next_match(omega_search_context_t *search_context_ptr, int64_t advance_context)

Given a search context, find the next match

Parameters:

search_context_ptr – search context to find the next match in
advance_context – advance the internal search context offset by this many bytes

Returns:

positive if a match is found, zero if no match remains, negative on search failure

void omega_search_destroy_context(omega_search_context_t *search_context_ptr)

Destroy the given search context

Parameters:: search_context_ptr – search context to destroy

session.h

Functions that operate on editing sessions (omega_session_t).

Defines

OMEGA_EDIT_BYTE_FREQUENCY_PROFILE_SIZE: Size of the byte frequency profile in bytes.

OMEGA_EDIT_PROFILE_DOS_EOL: Index for the DOS end-of-line byte pair (CR LF) in the byte frequency profile.

Typedefs

typedef int64_t omega_byte_frequency_profile_t[OMEGA_EDIT_BYTE_FREQUENCY_PROFILE_SIZE]: Byte frequency profile

Functions

int omega_session_byte_frequency_profile_size()

Get the size of the byte frequency profile in bytes

Returns:: size of the byte frequency profile in bytes

int omega_session_byte_frequency_profile_dos_eol_index()

Get the index for the DOS end-of-line byte pair (CR LF) in the byte frequency profile

Returns:: index for the DOS end-of-line byte pair (CR LF) in the byte frequency profile

const char *omega_session_get_file_path(const omega_session_t *session_ptr)

Given a session, return the file path being edited (if known)

Parameters:: session_ptr – session to return the file path from
Returns:: borrowed file path pointer, or null if not known. The returned pointer is owned by the session and remains valid only until the next session mutation or session destruction.

const char *omega_session_get_original_snapshot_file_path(const omega_session_t *session_ptr)

Given a session, return the OmegaEdit-owned immutable snapshot file captured at session creation.

Parameters:: session_ptr – session to inspect
Returns:: borrowed snapshot file path pointer, or null if unavailable. The returned pointer is owned by the session and remains valid only until the next session mutation or session destruction.

omega_session_event_cbk_t omega_session_get_event_cbk(const omega_session_t *session_ptr)

Given a session, return the session event callback

Parameters:: session_ptr – session to return the event callback from
Returns:: session event callback

int32_t omega_session_get_event_interest(const omega_session_t *session_ptr)

Given a session, return the session event interest

Parameters:: session_ptr – session to return the session event interest from
Returns:: session event interest

int32_t omega_session_set_event_interest(omega_session_t *session_ptr, int32_t event_interest)

Set the session event interest to the given session event interest for the the given session

Parameters:

session_ptr – session to set the session event interest for
event_interest – desired session event interest

Returns:

session event interest

void *omega_session_get_user_data_ptr(const omega_session_t *session_ptr)

Given a session, return the associated user data

Parameters:: session_ptr – session to get the associated user data from
Returns:: associated user data for the given session

int omega_session_get_segment(const omega_session_t *session_ptr, omega_segment_t *data_segment_ptr, int64_t offset)

Given a session and offset, populate a data segment

Parameters:

session_ptr – session to get a segment of data from
data_segment_ptr – data segment to populate
offset – session offset to begin getting data from

Returns:

zero on success, non-zero otherwise

int omega_session_get_original_segment(const omega_session_t *session_ptr, omega_segment_t *data_segment_ptr, int64_t offset)

Given a session, populate a segment from the immutable original session content.

Parameters:

session_ptr – session whose original content should be read
data_segment_ptr – data segment to populate
offset – original-content byte offset to read from

Returns:

0 if the segment is populated successfully and non-zero otherwise

int64_t omega_session_get_num_viewports(const omega_session_t *session_ptr)

Given a session, return the number of active viewports

Parameters:: session_ptr – session to get the number of active viewports for
Returns:: number of active viewports

int64_t omega_session_get_num_search_contexts(const omega_session_t *session_ptr)

Given a session, return the number of active search contexts

Parameters:: session_ptr – session to get the number of active search contexts for
Returns:: number of active search contexts

int64_t omega_session_get_num_changes(const omega_session_t *session_ptr)

Given a session, return the current number of active changes

Parameters:: session_ptr – session to get number of active changes from
Returns:: number of active changes

int64_t omega_session_get_num_undone_changes(const omega_session_t *session_ptr)

Given a session, return the current number of undone changes eligible for redo. This is the complete forward-retained suffix, including changes preserved in future checkpoint models.

Parameters:: session_ptr – session to get the number of redoable, forward-retained changes for
Returns:: number of redoable, forward-retained changes

int64_t omega_session_get_computed_file_size(const omega_session_t *session_ptr)

Given a session, return the computed file size in bytes

Parameters:: session_ptr – session to get the computed file size from
Returns:: computed file size in bytes, or -1 on failure

int64_t omega_session_get_original_file_size(const omega_session_t *session_ptr)

Given a session, return the original file size in bytes

Parameters:: session_ptr – session to inspect
Returns:: original file size in bytes, or -1 on failure

const char *omega_session_get_latest_checkpoint_file_path(const omega_session_t *session_ptr)

Given a session, return the OmegaEdit-owned immutable latest checkpoint file path.

Parameters:: session_ptr – session to inspect
Returns:: borrowed checkpoint file path pointer, or null if no checkpoint exists. The returned pointer is owned by the session and remains valid only until the next session mutation or session destruction.

int64_t omega_session_get_latest_checkpoint_file_size(const omega_session_t *session_ptr)

Given a session, return the byte size of the OmegaEdit-owned immutable latest checkpoint file.

Parameters:: session_ptr – session to inspect
Returns:: latest checkpoint size in bytes, or -1 if no checkpoint exists or the size cannot be read

const omega_change_t *omega_session_get_last_change(const omega_session_t *session_ptr)

Given a session, get the last change (if any)

Parameters:: session_ptr – session to get the last change from
Returns:: last change, or nullptr if there are no changes

const omega_change_t *omega_session_get_last_undo(const omega_session_t *session_ptr)

Given a session, get the last undone change eligible for redo (if any)

Parameters:: session_ptr – session to get the last undone change eligible for redo from
Returns:: last undone change eligible for redo, or nullptr if there are no eligible changes for redo

const omega_change_t *omega_session_get_change(const omega_session_t *session_ptr, int64_t change_serial)

Given a change serial, get the change

Parameters:

session_ptr – session to which the change belongs
change_serial – change serial of the change to get

Returns:

change with the matching serial, or nullptr on failure

int omega_session_viewport_event_callbacks_paused(const omega_session_t *session_ptr)

Determine if the viewport on-change callbacks have been paused or not

Parameters:: session_ptr – session to determine if viewport on-change callbacks are paused on
Returns:: non-zero if viewport on-change callbacks are paused and zero if they are not

void omega_session_pause_viewport_event_callbacks(omega_session_t *session_ptr)

Pause viewport on-change callbacks for the given session

Parameters:: session_ptr – session to pause viewport on-change callbacks on

void omega_session_resume_viewport_event_callbacks(omega_session_t *session_ptr)

Resume viewport on-change callbacks for the given session

Parameters:: session_ptr – session to resume viewport on-change callbacks on

int omega_session_notify_changed_viewports(const omega_session_t *session_ptr)

Notify changed viewports in the given session with a VIEWPORT_EVT_CHANGES event

Parameters:: session_ptr – session to notify viewports with changes
Returns:: number of viewports that were notified, or -1 on failure

int omega_session_changes_paused(const omega_session_t *session_ptr)

Determine if the session is accepting changes or not

Parameters:: session_ptr – session to determine if changes are accepted or not
Returns:: non-zero if the session is accepting changes and zero if it is not

void omega_session_pause_changes(omega_session_t *session_ptr)

Pause data changes to the session

Parameters:: session_ptr – session to pause changes to

void omega_session_resume_changes(omega_session_t *session_ptr)

Resume data changes to the session

Parameters:: session_ptr – session to resume changes to

int omega_session_begin_transaction(omega_session_t *session_ptr)

Given a session, begin a transaction

Parameters:: session_ptr – session to begin a transaction on
Returns:: 0 on success, non-zero otherwise

int omega_session_end_transaction(omega_session_t *session_ptr)

Given a session, end a transaction

Parameters:: session_ptr – session to end a transaction on
Returns:: 0 on success, non-zero otherwise

int omega_session_get_transaction_state(const omega_session_t *session_ptr)

Given a session, return the current transaction state

Parameters:: session_ptr – session to get the transaction state for
Returns:: 0 for no transaction, 1 for transaction is opened, and 2 for transaction in progress, and -1 on failure

int64_t omega_session_get_num_change_transactions(const omega_session_t *session_ptr)

Given a session, return the current number of session change transactions

Parameters:: session_ptr – session to get the number of session change transactions for
Returns:: number of session change transactions

int64_t omega_session_get_num_undone_change_transactions(const omega_session_t *session_ptr)

Given a session, return the current number of session undone change transactions

Parameters:: session_ptr – session to get the number of session undone change transactions for
Returns:: number of session undone change transactions

int64_t omega_session_get_num_checkpoints(const omega_session_t *session_ptr)

Given a session, return the current number of session checkpoints

Parameters:: session_ptr – session to get the number of session checkpoints for
Returns:: number of session checkpoints

int64_t omega_session_get_checkpoint_change_count(const omega_session_t *session_ptr, int64_t checkpoint_count)

Return the active change count represented by a checkpoint boundary. Checkpoint zero is the original session state; positive indices are active checkpoints through omega_session_get_num_checkpoints().

Returns:: active change count at the boundary, or -1 for invalid input

int64_t omega_session_get_checkpoint_at_change_count(const omega_session_t *session_ptr, int64_t change_count)

Return the newest checkpoint index whose boundary exactly matches an active change count.

Returns:: newest matching checkpoint index (including zero for the original state), or -1 when no boundary matches

int64_t omega_session_get_num_future_checkpoints(const omega_session_t *session_ptr)

Given a session, return the number of preserved checkpoints after the active checkpoint boundary.

Parameters:: session_ptr – session to get the number of future checkpoints for
Returns:: number of future checkpoints

void omega_session_notify(const omega_session_t *session_ptr, omega_session_event_t session_event, const void *event_ptr)

Call the registered session event handler

Parameters:

session_ptr – session whose event handler to call
session_event – session event
event_ptr – pointer to the change

omega_bom_t omega_session_detect_BOM(const omega_session_t *session_ptr, int64_t offset)

Given a session, return the detected byte order marker (BOM)

Parameters:

session_ptr – session to get the BOM from
offset – where in the session to begin detecting the BOM

Returns:

detected byte order marker (BOM)

int omega_session_byte_frequency_profile(const omega_session_t *session_ptr, omega_byte_frequency_profile_t *profile_ptr, int64_t offset, int64_t length)

Given a session, offset and length, populate a byte frequency profile

Parameters:

session_ptr – session to profile
profile_ptr – pointer to the byte frequency profile to populate
offset – where in the session to begin profiling
length – number of bytes from the offset to stop profiling (if 0, it will profile to the end of the session)

Returns:

zero on success and non-zero otherwise

int omega_session_character_counts(const omega_session_t *session_ptr, omega_character_counts_t *counts_ptr, int64_t offset, int64_t length, omega_bom_t bom)

Given a session, offset and length, populate character counts

Parameters:

session_ptr – session to count characters in
counts_ptr – pointer to the character counts to populate
offset – where in the session to begin counting characters
length – number of bytes from the offset to stop counting characters (if 0, it will count to the end of the session)
bom – byte order marker (BOM) to use when counting characters

Returns:

zero on success and non-zero otherwise

const char *omega_session_get_checkpoint_directory(const omega_session_t *session_ptr)

Given a session, return the checkpoint directory

Parameters:: session_ptr – session to get the checkpoint directory for
Returns:: checkpoint directory

int64_t omega_session_get_checkpoint_directory_length(const omega_session_t *session_ptr)

Given a session, return the checkpoint directory path string length

Parameters:: session_ptr – session to get the checkpoint directory for
Returns:: string length of the checkpoint directory

int64_t omega_session_get_undo_snapshot_interval(const omega_session_t *session_ptr)

Given a session, return the undo model snapshot interval. When greater than zero, the session takes periodic snapshots of the model segments to accelerate undo operations. A value of 0 disables snapshots.

Parameters:: session_ptr – session to get the undo snapshot interval for
Returns:: undo snapshot interval (number of changes between snapshots), or 0 if disabled/null

int64_t omega_session_set_undo_snapshot_interval(omega_session_t *session_ptr, int64_t interval)

Set the undo model snapshot interval for a session. When greater than zero, the session takes periodic snapshots of the model segments to accelerate undo operations. A value of 0 disables snapshots.

Parameters:

session_ptr – session to set the undo snapshot interval for
interval – number of changes between snapshots (0 to disable)

Returns:

the new interval, or 0 on error

int64_t omega_session_get_change_inline_payload_limit(const omega_session_t *session_ptr)

Given a session, return the inline primitive payload threshold. Change payloads larger than this threshold are stored in session-owned backing files when possible.

Parameters:: session_ptr – session to get the inline primitive payload threshold for
Returns:: threshold in bytes, or 0 for null sessions

int64_t omega_session_set_change_inline_payload_limit(omega_session_t *session_ptr, int64_t limit)

Set the inline primitive payload threshold for a session. A value of 0 stores every non-empty captured primitive payload in a backing file. Values above OMEGA_MEMORY_BUFFER_LIMIT are accepted, but materialized public byte buffers are still limited by OMEGA_MEMORY_BUFFER_LIMIT.

Parameters:

session_ptr – session to set the inline primitive payload threshold for
limit – threshold in bytes

Returns:

the new threshold, or 0 on error

stl_string_adaptor.hpp

C++ convenience functions for using STL strings.

utility.h

Various utility functions.

Typedefs

typedef omega_byte_t (*omega_util_byte_transform_t)(omega_byte_t, void *user_data): Byte transform function pointer

Functions

int omega_util_compute_mode(int mode)

Returns the file mode modulo umask

Parameters:: mode – file mode
Returns:: file mode modulo umask

int64_t omega_util_write_segment_to_file(FILE *from_file_ptr, int64_t offset, int64_t byte_count, FILE *to_file_ptr)

Write a segment from one file into another file

Parameters:

from_file_ptr – from file pointer, opened for read
offset – where in the from file to begin reading from
byte_count – number of bytes to read from the from file starting at the given offset
to_file_ptr – to file pointer, opened for writing and positioned to where to write the segment to

Returns:

number of bytes that where successfully written

int omega_util_left_shift_buffer(omega_byte_t *buffer, int64_t len, omega_byte_t shift_left, int fill_bit)

Shift the bits of the given buffer by a given number of bits to the left towards the start of the buffer

Parameters:

buffer – pointer to the start of the buffer
len – length of the buffer
shift_left – number of bits (greater than 0 and less than 8) to shift to the left
fill_bit – bit to fill the shifted bit vacancies created at the end of the buffer with (0 or 1)

Returns:

zero on success, non-zero on failure

int omega_util_right_shift_buffer(omega_byte_t *buffer, int64_t len, omega_byte_t shift_right, int fill_bit)

Shift the bits of the given buffer by a given number of bits to the right towards the end of the buffer

Parameters:

buffer – pointer to the start of the buffer
len – length of the buffer
shift_right – number of bits (greater than 0 and less than 8) to shift to the right
fill_bit – bit to fill the shifted bit vacancies created at the beginning of the buffer with (0 or 1)

Returns:

zero on success, non-zero on failure

void omega_util_apply_byte_transform(omega_byte_t *buffer, int64_t len, omega_util_byte_transform_t transform, void *user_data_ptr)

Apply the given transform to bytes in the given buffer

Parameters:

buffer – buffer of bytes to apply the transform to
len – number of bytes in the buffer to apply the transform to
transform – transform function to apply to the bytes in the buffer
user_data_ptr – pointer to user-defined data to associate with the transformer

int omega_util_apply_byte_transform_to_file(char const *in_path, char const *out_path, omega_util_byte_transform_t transform, void *user_data_ptr, int64_t offset, int64_t length)

Apply the given transform to the input file and write the transformed data to the output file

Parameters:

in_path – path of the file to apply the transform to
out_path – path of the file to write the transformed data to
transform – byte transform function to apply
user_data_ptr – pointer to user-defined data to associate with the transformer
offset – where to begin transforming bytes
length – number of bytes to transform from the given offset

Returns:

zero on success, non-zero on failure

omega_byte_t omega_util_mask_byte(omega_byte_t byte, omega_byte_t mask, omega_mask_kind_t mask_kind)

Apply the given mask of the given mask kind to the given byte

Parameters:

byte – byte to mask
mask – mask to apply
mask_kind – mask kind (e.g., MASK_AND, MASK_OR, MASK_XOR)

Returns:

masked byte

int omega_util_strncmp(const char *s1, const char *s2, uint64_t sz)

Compares sz bytes of two character strings

Parameters:

s1 – first character string
s2 – second character string
sz – number of bytes to compare

Returns:

zero if sz bytes of the two character strings match, non-zero otherwise

int omega_util_strnicmp(const char *s1, const char *s2, uint64_t sz)

Compares sz bytes of two character strings, without regard to case (case insensitive)

Parameters:

s1 – first character string
s2 – second character string
sz – number of bytes to compare

Returns:

zero if sz bytes of the two character strings match, non-zero otherwise

char *omega_util_strndup(const char *s, size_t n)

Cross-platform strndup work-alike

Parameters:

s – string to duplicate
n – length of the string to duplicate

Returns:

duplicated , null terminated string, allocated with malloc, or NULL on failure

const void *omega_util_memrchr(const void *s, int c, size_t n)

Cross-platform memrchr work-alike

Parameters:

s – memory to search
c – byte to search for
n – number of bytes to search

omega_bom_t omega_util_detect_BOM_from_memory(const unsigned char *data, size_t length)

Detect the byte order mark (BOM) of the given memory

Parameters:

data – memory to detect the BOM of
length – length of the memory to detect the BOM of

Returns:

BOM_NONE if no BOM is detected, otherwise the detected BOM

omega_bom_t omega_util_detect_BOM_from_file(const char *filename)

Detect the byte order mark (BOM) of the given file

Parameters:: filename – path of the file to detect the BOM of
Returns:: BOM_NONE if no BOM is detected, otherwise the detected BOM

char const *omega_util_BOM_to_cstring(omega_bom_t bom)

Convert the given byte order mark (BOM) to a string

Parameters:: bom – byte order mark (BOM) to convert
Returns:: C-string representation of the given BOM (“none”, “UTF-8”, “UTF-16LE”, “UTF-16BE”, “UTF-32LE”, “UTF-32BE”)

omega_bom_t omega_util_cstring_to_BOM(char const *str)

void omega_util_count_characters(const unsigned char *data, size_t length, omega_character_counts_t *counts_ptr)

Count the number of single byte, and multi-byte characters in the given data

Note

make sure the BOM is set in the given character counts before calling this function

Parameters:

data – data to count the characters in
length – length of the data
counts_ptr – pointer to the character counts to populate

size_t omega_util_BOM_size(omega_bom_t bom)

Given a byte order mark (BOM), return the size of the byte order mark (BOM) in bytes

Parameters:: bom – byte order mark (BOM) to get the size of
Returns:: size of the byte order mark (BOM) in bytes

const omega_byte_buffer_t *omega_util_BOM_to_buffer(omega_bom_t bom)

Get the byte order mark buffer (BOM) associated with the given byte order mark (BOM)

Parameters:: bom – byte order mark (BOM) to get
Returns:: byte buffer containing the given BOM, or NULL if the given BOM is BOM_NONE

struct omega_byte_buffer_t

#include <utility.h>

Byte buffer

Public Members

const omega_byte_t *data: The data in the buffer

size_t length: The length of the buffer

version.h

Functions that return version information.

Functions

int omega_version_major()

Get the major version of the library

Returns:: the major version of the library

int omega_version_minor()

Get the minor version of the library

Returns:: the minor version of the library

int omega_version_patch()

Get the patch-level of the library

Returns:: the patch-level of the library

int omega_version()

Get the integer representation of the version of the library

Returns:

the integer representation of the version of the library

auto version = omega_version();
auto major = (version >> 24) & 0xFF;
auto minor = (version >> 16) & 0xFF;
auto patch = version & 0xFF;

char const *omega_libtype()

Returns “shared” if the library has been built as a shared library, or “static” if the library is built as a static library

Returns:: “shared” if the library has been built as a shared library, or “static” if the library is built as a static library

viewport.h

Functions that operate on viewports (omega_viewport_t).

Functions

const omega_session_t *omega_viewport_get_session(const omega_viewport_t *viewport_ptr)

Given a viewport, return the session pointer

Parameters:: viewport_ptr – viewport to get the session pointer from
Returns:: viewport session pointer

int64_t omega_viewport_get_capacity(const omega_viewport_t *viewport_ptr)

Given a viewport, return the viewport capacity

Parameters:: viewport_ptr – viewport to get the capacity from
Returns:: viewport capacity

int64_t omega_viewport_get_length(const omega_viewport_t *viewport_ptr)

Given a viewport, return the viewport data length

Parameters:: viewport_ptr – viewport to get the viewport data length from
Returns:: viewport data length

const omega_byte_t *omega_viewport_get_data(const omega_viewport_t *viewport_ptr)

Given a viewport, return the viewport data

Parameters:: viewport_ptr – viewport to get the viewport data from
Returns:: viewport data

int omega_viewport_has_changes(const omega_viewport_t *viewport_ptr)

Given a viewport, determine if it contains changes since the last omega_viewport_get_data call

Parameters:: viewport_ptr – viewport to determine if changes are present
Returns:: 0 if there are no changes present, and non-zero otherwise

int64_t omega_viewport_get_offset(const omega_viewport_t *viewport_ptr)

Given a viewport, return the viewport offset

Parameters:: viewport_ptr – viewport to get the viewport offset from
Returns:: viewport offset

int omega_viewport_is_floating(const omega_viewport_t *viewport_ptr)

Given a viewport, return non-zero if the viewport is floating and zero if the viewport is fixed

Parameters:: viewport_ptr – viewport to determine if its floating or not
Returns:: non-zero if the viewport is floating and zero if the viewport is fixed

int64_t omega_viewport_get_following_byte_count(const omega_viewport_t *viewport_ptr)

Given a viewport, return the number of bytes that exist after the viewport

Parameters:: viewport_ptr – viewport to get the number of bytes that exist after the viewport from
Returns:: number of bytes that exist after the viewport

void *omega_viewport_get_user_data_ptr(const omega_viewport_t *viewport_ptr)

Given a viewport, return the viewport user data

Parameters:: viewport_ptr – viewport to get the user data from
Returns:: viewport user data

omega_viewport_event_cbk_t omega_viewport_get_event_cbk(const omega_viewport_t *viewport_ptr)

Given a session, return the viewport event callback

Parameters:: viewport_ptr – viewport to return the event callback from
Returns:: viewport event callback

int32_t omega_viewport_get_event_interest(const omega_viewport_t *viewport_ptr)

Given a viewport, return the viewport event interest

Parameters:: viewport_ptr – viewport to return the viewport event interest from
Returns:: viewport event interest

int32_t omega_viewport_set_event_interest(omega_viewport_t *viewport_ptr, int32_t event_interest)

Set the viewport event interest to the given viewport event interest for the the given viewport

Parameters:

viewport_ptr – viewport
event_interest – desired viewport event interest

Returns:

viewport event interest

int omega_viewport_modify(omega_viewport_t *viewport_ptr, int64_t offset, int64_t capacity, int is_floating)

Change viewport settings

Parameters:

viewport_ptr – viewport to change settings on
offset – offset for the viewport
capacity – capacity of the viewport
is_floating – 0 if the viewport is to remain fixed at the given offset, non-zero if the viewport is expected to “float” as bytes are inserted or deleted before the start of this viewport

Returns:

0 on success, non-zero otherwise

int omega_viewport_modify_with_options(omega_viewport_t *viewport_ptr, const omega_viewport_modify_options_t *options)

Change viewport settings using named options.

Parameters:

viewport_ptr – viewport to change settings on
options – viewport modification options

Returns:

0 on success, non-zero otherwise

int omega_viewport_in_segment(const omega_viewport_t *viewport_ptr, int64_t offset, int64_t length)

Determine if the given viewport is in the given segment

Parameters:

viewport_ptr – viewport to determine if it’s in the given segment
offset – beginning offset of the segment
length – length of the segment

Returns:

non-zero if the viewport is in the given segment and zero otherwise

int omega_viewport_notify(const omega_viewport_t *viewport_ptr, omega_viewport_event_t viewport_event, const void *event_ptr)

Execute the viewport on-change callback with the given change if a viewport on-change callback is defined and if the session where this viewport lives does not currently have viewport on-change callbacks paused

Parameters:

viewport_ptr – viewport for which to execute its on-change callback
viewport_event – event kind that is taking place
event_ptr – change responsible for the viewport change (if any)

Returns:

1 if the viewport on-change callback was executed, 0 if the viewport on-change callback was not executed

struct omega_viewport_modify_options_t

#include <viewport.h>

Options for modifying viewport settings with named fields.

Public Members

int64_t offset

int64_t capacity

omega_edit_bool_t is_floating

visit.h

Functions that enable visiting changes in an editing session.

Typedefs

typedef int (*omega_session_change_visitor_cbk_t)(const omega_change_t*, void*): Callback to implement for visiting changes in a session. Return 0 to continue visiting changes and non-zero to stop.

typedef int (*omega_retained_history_visitor_cbk_t)(const omega_change_t*, int64_t serial, void*): Callback for visiting retained active/redo history. The serial argument is the positive logical history serial.

typedef struct omega_visit_change_context_struct omega_visit_change_context_t: Opaque visit change context

Functions

int omega_visit_changes(const omega_session_t *session_ptr, omega_session_change_visitor_cbk_t cbk, void *user_data)

Visit changes in the given session in chronological order (oldest first), if the callback returns an integer other than 0, visitation will stop and the return value of the callback will be this function’s return value

Parameters:

session_ptr – session to visit changes in
cbk – user-provided function to call for each change
user_data – user-provided data to provide back to the callback

Returns:

0 if all changes were visited or the non-zero return value of the callback if visitation was stopped early

int omega_visit_changes_reverse(const omega_session_t *session_ptr, omega_session_change_visitor_cbk_t cbk, void *user_data)

Visit changes in the given session in reverse chronological order (newest first), if the callback returns an integer other than 0, visitation will stop and the return value of the callback will be this function’s return value

Parameters:

session_ptr – session to visit changes in
cbk – user-provided function to call for each change
user_data – user-provided data to provide back to the callback

Returns:

0 if all changes were visited or the non-zero return value of the callback if visitation was stopped early

int omega_visit_retained_history(const omega_session_t *session_ptr, int64_t first_serial, int64_t last_serial, int reverse, omega_retained_history_visitor_cbk_t cbk, void *user_data)

Visit a bounded inclusive range of active and redoable retained history in logical serial order.

Parameters:

session_ptr – session whose retained history should be visited
first_serial – first positive logical serial to include
last_serial – last positive logical serial to include
reverse – non-zero to visit newest-to-oldest, otherwise oldest-to-newest
cbk – user-provided callback
user_data – user-provided callback data

Returns:

0 when the range was visited, -1 for invalid history/range, or the callback’s non-zero return value

omega_visit_change_context_t *omega_visit_change_create_context(const omega_session_t *session_ptr, int reverse)

Create a change visitor context

Parameters:

session_ptr – session to visit changes
reverse – non-zero to reverse the visitation chronology (newest change to oldest change)

Returns:

change visitor context

int omega_visit_change_at_end(const omega_visit_change_context_t *change_context_ptr)

Return non-zero if we are at the end of the change visitations

Parameters:: change_context_ptr – change visitor context to see if we’re at the end of
Returns:: non-zero if we are at the end of the change visitations and zero if there are changes remaining to visit

int omega_visit_change_begin(omega_visit_change_context_t *change_context_ptr)

Set the change visitor context to the beginning of the changes

Parameters:: change_context_ptr – change visitor context to set to the beginning
Returns:: non-zero if there are no changes to visit and zero otherwise

int omega_visit_change_next(omega_visit_change_context_t *change_context_ptr)

Given a change visitor context, find the next change

Parameters:: change_context_ptr – change visitor context to find the next change in
Returns:: non-zero if a change is found, zero otherwise

const omega_change_t *omega_visit_change_context_get_change(const omega_visit_change_context_t *change_context_ptr)

Given a change visitor context, get a pointer to the change

Parameters:: change_context_ptr – change visitor context to get the change from
Returns:: pointer to the change, or nullptr if no change is found

void omega_visit_change_destroy_context(omega_visit_change_context_t *change_context_ptr)

Destroy the given change visitor context

Parameters:: change_context_ptr – change visitor context to destroy