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

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’, and ‘O’)

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

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)

const omega_byte_t *omega_change_get_bytes(const omega_change_t *change_ptr)

Given a change, return a pointer to the byte data

Parameters:: change_ptr – change to get the bytes data from
Returns:: pointer to the byte data

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

DEBUG: Define to enable debugging

OMEGA_VIEWPORT_CAPACITY_LIMIT: Default maximum viewport capacity

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

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 fseeko if _LARGEFILE_SOURCE is defined to accommodate large files.

FTELL: Alias for the ftell/ftello function, using ftello if _LARGEFILE_SOURCE is defined 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.

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

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

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

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_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

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, zero otherwise

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

If editing data that could have embedded nulls, do not rely on setting the length to 0 and have this function compute the length using strlen, because it will be wrong. Passing length 0 is a convenience for testing and should not be used in production code. In production code, explicitly pass in the length.

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 – number of bytes to insert (if 0, strlen will be used to calculate the length of null-terminated bytes)

Returns:

positive change serial number on success, zero otherwise

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

If editing data that could have embedded nulls, do not rely on setting the length to 0 and have this function compute the length using strlen, because it will be wrong. Passing length 0 is a convenience for testing and should not be used in production code. In production code, explicitly pass in the 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, zero otherwise

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

If editing data that could have embedded nulls, do not rely on setting the length to 0 and have this function compute the length using strlen, because it will be wrong. Passing length 0 is a convenience for testing and should not be used in production code. In production code, explicitly pass in the length.

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 – number of new bytes (if 0, strlen will be used to calculate the length of null-terminated bytes)

Returns:

positive change serial number on success, zero otherwise

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

If editing data that could have embedded nulls, do not rely on setting the length to 0 and have this function compute the length using strlen, because it will be wrong. Passing length 0 is a convenience for testing and should not be used in production code. In production code, explicitly pass in the 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, 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

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) bytes
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

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

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

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

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

ALL_EVENTS: Subscribe to all 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

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

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_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.

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, int case_insensitive, int is_reverse_search)

Create a search context

Warning

If searching for pattern data that could have embedded nulls, do not rely on setting the length to 0 and have this function compute the length using strlen, because it will be wrong. Passing pattern length 0 is a convenience for testing and should not be used in production code. In production code, explicitly pass in the 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 patterns in
pattern – pointer to the pattern to find (as a sequence of bytes)
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 track the computed session length
case_insensitive – zero for case sensitive match and non-zero otherwise
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, int case_insensitive, int is_reverse_search)

Create a search context

Warning

If searching for pattern data that could have embedded nulls, do not rely on setting the length to 0 and have this function compute the length using strlen, because it will be wrong. Passing length 0 is a convenience for testing and should not be used in production code. In production code, explicitly pass in the 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_insensitive – zero for case-sensitive matching and non-zero for case-insensitive 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:

non-zero if a match is found, zero otherwise

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:: file path, or null if not known

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

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 being redone

Parameters:: session_ptr – session to get the number of undone changes for
Returns:: number of undone changes eligible for being redone

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

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

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

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_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

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 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

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