4coder API

The command_id parameter specifies which internal command to execute.

If the view parameter is non-null it specifies a view to display the command's output buffer.

The buffer the command will output to is specified by the buffer parameter. See Buffer_Identifier for information on how this type specifies a buffer.

The path parameter specifies the path in which the command shall be executed. The string need not be null terminated.

The parameter path_len specifies the length of the path string.

The command parameter specifies the command that shall be executed. The string need not be null terminated.

The parameter command_len specifies the length of the command string.

Flags for the behavior of the call are specified in the flags parameter.

This parameter is set up to prepare for future features, it should always be 0 for now.

The str parameter specifies the string to be posted to the clipboard, it need not be null terminated.

The len parameter specifies the length of the str string.

This parameter is set up to prepare for future features, it should always be 0 for now.

This parameter is set up to prepare for future features, it should always be 0 for now.

This parameter specifies which item to read, 0 is the most recent copy, 1 is the second most recent copy, etc.

This parameter provides a buffer where the clipboard contents are written. This parameter may be NULL.

This parameter specifies the length of the out buffer.

The access parameter determines what levels of protection this call can access.

The Buffer_Summary pointed to by buffer is iterated to the next buffer or to a null summary if this is the last buffer.

The access parameter determines what levels of protection this call can access. The buffer outputted will be the next buffer that is accessible.

The parameter buffer_id specifies which buffer to try to get.

The access parameter determines what levels of protection this call can access.

The name parameter specifies the buffer name to try to get. The string need not be null terminated.

The len parameter specifies the length of the name string.

The access parameter determines what levels of protection this call can access.

This parameter specifies the buffer to read.

This parameter specifies absolute position of the first character in the read range.

This parameter specifies the absolute position of the the character one past the end of the read range.

This paramter provides the output character buffer to fill with the result of the read.

This parameter specifies the buffer to edit.

This parameter specifies absolute position of the first character in the replace range.

This parameter specifies the absolute position of the the character one past the end of the replace range.

This parameter specifies the the string to write into the range; it need not be null terminated.

This parameter specifies the length of the str string.

The buffer parameter specifies the buffer on which to run the cursor computation.

The seek parameter specifies the target position for the seek.

On success this struct is filled with the result of the seek.

The buffer on which to apply the batch of edits.

This parameter provides all of the source string for the edits in the batch.

This parameter specifies the length of the str string.

This parameter provides about the source string and destination range of each edit as an array.

This parameter specifies the number of Buffer_Edit structs in edits.

This prameter specifies what type of batch edit to execute.

The buffer parameter specifies the buffer on which to set a setting.

The setting parameter identifies the setting that shall be changed.

The value parameter specifies the value to which the setting shall be changed.

Specifies the buffer from which to read the token count.

Specifies the buffer from which to read tokens.

Specifies the index of the first token to read.

Specifies the token to stop reading at.

The memory that will store the tokens read from the buffer.

The buffer from which to get a token.

The position in the buffer in absolute coordinates.

The output struct specifying which token contains pos.

The filename parameter specifies the name of the file to be opened or created; it need not be null terminated.

The filename_len parameter spcifies the length of the filename string.

The flags parameter specifies behaviors for buffer creation.

The buffer parameter specifies the buffer to save to a file.

The filename parameter specifies the name of the file to associated to the buffer; it need not be null terminated.

The filename_len parameter specifies the length of the filename string.

This parameter is not currently used and should be set to 0 for now.

The buffer parameter specifies the buffer to try to kill.

The view_id parameter specifies the view that will contain the "are you sure" dialogue if the buffer is dirty.

The flags parameter specifies behaviors for the buffer kill.

The access parameter determines what levels of protection this call can access.

The View_Summary pointed to by view is iterated to the next view or to a null summary if this is the last view.

The access parameter determines what levels of protection this call can access. The view outputted will be the next view that is accessible.

The view_id specifies the view to try to get.

The access parameter determines what levels of protection this call can access.

The access parameter determines what levels of protection this call can access.

The view_location parameter specifies the view to split to open the new view.

The position parameter specifies how to split the view and where to place the new view.

The view parameter specifies which view to close.

The view parameter specifies which view to make active.

The view parameter specifies the view on which to set a setting.

The setting parameter identifies the setting that shall be changed.

The value parameter specifies the value to which the setting shall be changed.

The view parameter specifies which view shall have it's size adjusted.

The t parameter specifies the proportion of the containing box that the view should occupy. t should be in [0,1].

The view parameter specifies the view on which to run the cursor computation.

The seek parameter specifies the target position for the seek.

On success this struct is filled with the result of the seek.

The view parameter specifies the view in which to set the cursor.

The seek parameter specifies the target position for the seek.

If this parameter is true the preferred x is updated to match the new cursor x.

The view parameter specifies the view in which to set the mark.

The seek parameter specifies the target position for the seek.

The view parameter specifies the view in which to set the highlight.

This parameter specifies the absolute position of the first character of the highlight range.

This parameter specifies the absolute position of the character one past the end of the highlight range.

This parameter indicates whether the highlight is being turned on or off.

The view parameter specifies the view in which to display the buffer.

The buffer_id parameter specifies which buffer to show in the view.

The flags parameter specifies behaviors for setting the buffer.

The view parameter specifies the view onto which the fade effect shall be posted.

This parameter specifies the number of seconds the fade effect should last.

This parameter specifies the absolute position of the first character of the fade range.

This parameter specifies the absolute position of the character one past the end of the fdae range.

The color parameter specifies the initial color of the text before it fades to it's natural color.

The get_type parameter specifies the set of input types that should be returned.

The get_type parameter specifies the set of input types that should trigger an abort signal.

This parameter provides a Query_Bar that should remain in valid memory until end_query_bar or the end of the command. It is commonly a good idea to make this a pointer to a Query_Bar stored on the stack.

This parameter is not currently used and should be 0 for now.

This parameter should be a bar pointer of a currently active query bar.

This parameter is not currently used and should be 0 for now.

The str parameter specifies the string to post to *messages*; it need not be null terminated.

The len parameter specifies the length of the str string.

The name parameter specifies the name of the theme to begin using; it need not be null terminated.

The len parameter specifies the length of the name string.

The name parameter specifies the name of the font to begin using; it need not be null terminated.

The len parameter specifies the length of the name string.

If this is set all open files change to this font. Usually this should be true durring the start hook because several files already exist at that time.

This parameter the buffer that shall have it's font changed

The name parameter specifies the name of the font to begin using; it need not be null terminated.

The len parameter specifies the length of the name string.

The colors pointer provides an array of color structs pairing differet style tags to color codes.

The count parameter specifies the number of Theme_Color structs in the colors array.

an array of color structs listing style tags to get color values for

the number of color structs in the colors array

This parameter provides a character buffer that receives the 4coder 'hot directory'.

This parameter specifies the maximum size to be output to the out buffer.

This parameter specifies the directory whose files will be enumerated in the returned list; it need not be null terminated.

This parameter the length of the dir string.

This parameter provides the file list to be freed.

The size in bytes of the block that should be returned.

The base of the block on which to set memory protection flags.

The size that was originally used to allocate this block.

The new memory protection flags.

The base of a block to free.

The size that was originally used to allocate this block.

This parameter specifies the full path to a file; it need not be null terminated.

This parameter specifies the length of the filename string.

This parameter provides a character buffer that stores a directory; it need not be null terminated.

This parameter specifies the length of the dir string.

This parameter specifies the maximum size of the dir string.

This parameter specifies the path to change to, may include '.' or '..'; it need not be null terminated.

This parameter specifies the length of the rel_path string.

This parameter provides a character buffer that receives the path to the 4ed executable file.

This parameter specifies the maximum capacity of the out buffer.

This parameter specifies the new state of the mouse cursor.

MDFR_INDEX_COUNT is used to specify the number of modifiers supported.

MDFR_NONE specifies that no modifiers are pressed.

cmdid_null is set aside to always be zero and is not associated with any command.

cmdid_undo performs a standard undo behavior.

cmdid_redo reperforms an edit that was undone.

cmdid_history_backward performs a step backwards through the file history, which includes previously lost redo branches.

cmdid_history_forward unperforms the previous cmdid_history_backward step if possible.

cmdid_interactive_new begins an interactive dialogue to create a new buffer.

cmdid_interactive_open begins an interactive dialogue to open a file into a buffer.

cmdid_save_as does not currently work and is likely to be removed rather that fixed.

cmdid_interactive_switch_buffer begins an interactive dialogue to choose an open buffer to swap into the active view.

cmdid_interactive_kill_buffer begins an interactive dialogue to choose an open buffer to kill.

cmdid_reopen reloads the active buffer's associated file and discards the old buffer contents for the reloaded file.

cmdid_save saves the buffer's contents into the associated file.

cmdid_kill_buffer tries to kill the active buffer.

cmdid_open_color_tweaker opens the theme editing GUI.

cmdid_open_config opens the configuration menu.

cmdid_open_menu opens the top level menu.

cmdid_open_debug opens the debug information viewer mode.

TODO

TODO

TODO

UserInputNone indicates that no event has occurred.

UserInputKey indicates an event which can be described by a Key_Event_Data struct.

UserInputMouse indicates an event which can be described by a Mouse_State struct.

TODO.

TODO.

TODO.

TODO.

BufferSetting_Null is not a valid setting, it is reserved to detect errors.

The BufferSetting_Lex setting is used to determine whether to store C++ tokens from with the buffer.

The BufferSetting_WrapLine setting is used to determine whether a buffer prefers to be viewed with wrapped lines, individual views can be set to override this value after being tied to the buffer.

The BufferSetting_MapID setting specifies the id of the command map that should be active when a buffer is active.

The BufferSetting_Eol setting specifies how line ends should be saved to the backing file. A 1 indicates dos endings "\r\n" and a 0 indicates nix endings "\n".

The BufferSetting_Unimportant setting marks a buffer so that it's dirty state will be completely ignored. This means the "dirty" star is hidden and the buffer can be closed without presenting an "are you sure" dialogue screen.

The BufferSetting_ReadOnly setting marks a buffer so that it can only be returned from buffer access calls that include an AccessProtected flag.

ViewSetting_Null is not a valid setting, it is reserved to detect errors.

The ViewSetting_WrapLine setting determines whether the view applies line wrapping at the border of the panel for long lines. Whenever the view switches to a new buffer it will reset this setting to match the 'preferred' line wrapping setting of the buffer.

The ViewSetting_ShowWhitespace setting determines whether the view highlights whitespace in a file. Whenever the view switches to a new buffer this setting is turned off.

The ViewSetting_ShowScrollbar setting determines whether a scroll bar is attached to a view in it's scrollable section.

BufferCreate_Background is not currently implemented.

When BufferCreate_AlwaysNew is set it indicates the buffer should be cleared to empty even if it's associated file already has content.

When BufferCreate_NeverNew is set it indicates that the buffer should only be created if it is an existing file or if a buffer with the given name is already open.

BufferKill_Background is not currently implemented.

When BufferKill_AlwaysKill is set it indicates the buffer should be killed without asking, even when the buffer is dirty.

AccessOpen does not include any bits, it indicates that the access should only return objects that have no protection flags set.

AccessProtected is set on buffers and views that are "read only" such as the output from an app->exec_system_command call such as *build*. This is to prevent the user from accidentally editing output that they might prefer to keep in tact.

AccessHidden is set on any view that is not currently showing it's file, for instance because it is navigating the file system to open a file.

AccessAll is a catchall access for cases where an access call should always return an object no matter what it's protection flags are.

DirtyState_UpToDate indicates that there are no unsaved changes and the underlying system file still agrees with the buffer's state.

DirtyState_UnsavedChanges indicates that there have been changes in the buffer since the last sync point.

DirtyState_UnsavedChanges indicates that the underlying file has been edited since the last sync point with the buffer.

If CLI_OverlapWithConflict is set if output buffer of the new command is already in use by another command which is still executing, the older command relinquishes control of the buffer and both operate simultaneously with only the newer command outputting to the buffer.

If CLI_AlwaysBindToView is set the output buffer will always be set in the active view even if it is already set in another open view.

If CLI_CursorAtEnd is set the cursor will be kept at the end of the output buffer, otherwise the cursor is kept at the beginning.

If AutoIndent_ClearLine is set, then any line that is only whitespace will be cleared to contain nothing at all. otherwise the line is filled with whitespace to match the nearby indentation.

If AutoIndent_UseTab is set, then when putting in leading whitespace to align code, as many tabs will be used as possible until the fine grained control of spaces is needed to finish the alignment.

If AutoIndent_ExactAlignBlock is set, then block comments are indented by putting the first non-whitespace character of the line in line with the beginning of the comment.

If AutoIndent_FullTokens is set, then the set of lines that are indented is automatically expanded so that any token spanning multiple lines gets entirely indented.

If SetBuffer_KeepOriginalGUI then when the file is set, the view will not switch to it if some other GUI was currently up, otherwise any GUI that is up is closed and the view switches to the file.

If EventOnAnyKey is set, all keyboard events are included in the set.

If EventOnEsc is set, any press of the escape key is included in the set.

If EventOnLeftButton is set, left clicks are included in the set.

If EventOnRightButton is set, right clicks are included in the set.

If EventOnWheel is set, any wheel movement is included in the set.

This is not totally implemented yet.

If EventOnButton is set, all mouse button events are included in the set.

This is not totally implemented yet.

EventAll is a catch all name for including all possible events in the set.

The MouseCursorShow_Never mode never shows the cursor.

The MouseCursorShow_Never mode always shows the cursor.

This value indicates absolute positioning where positions are measured as the number of bytes from the start of the file.

This value indicates xy positioning with wrapped lines where the x and y values are in pixels.

This value indicates xy positioning with unwrapped lines where the x and y values are in pixels.

This value indicates line-character, or line-column positioning. These coordinates are 1 based to match standard line numbering.

This value indicates that the new view should be above the existing view.

This value indicates that the new view should be below the existing view.

This value indicates that the new view should be left of the existing view.

This value indicates that the new view should be right of the existing view.

If this Generic_Command represents an internal command the cmdid field will have a value less than cmdid_count, and this field is the command id for the command.

If this Generic_Command does not represent an internal command the command field is the pointer to the custom command..

This field is the raw keycode which is always non-zero in valid key events.

This field is the keycode after translation to a character, this is 0 if there is no translation.

This field is like the field character, except that the state of caps lock is ignored in the translation.

This field is an array indicating the state of modifiers at the time of the key press. The array is indexed using the values of Key_Modifier. A 1 indicates that the corresponding modifier was held, and a 0 indicates that it was not held.

This field indicates that the left button is held.

This field indicates that the right button is held.

This field indicates that the left button was pressed this frame.

This field indicates that the right button was pressed this frame.

This field indicates that the left button was released this frame.

This field indicates that the right button was released this frame.

This field is 0 when the wheel has not moved, it is 1 for a downward motion and -1 for an upward motion.

This field indicates that the mouse is outside of the window.

This field contains the x position of the mouse relative to the window where the left side is 0.

This field contains the y position of the mouse relative to the window where the top side is 0.

int32_t min;
int32_t max;

int32_t start;
int32_t end;

This is the smaller value in the range, it is also the 'start'.

This is the larger value in the range, it is also the 'end'.

This is the start of the range, it is also the 'min'.

This is the end of the range, it is also the 'max'.

This field is a null terminated string specifying the name of the file.

This field specifies the length of the filename string not counting the null terminator.

This field indicates that the description is for a folder not a file.

This field is for inernal use.

This field is an array of File_Info structs.

This field specifies the number of struts in the info array.

This field is for internal use.

This field is the name of the buffer; it need not be null terminated. If id is specified this pointer should be NULL.

This field specifies the length of the name string.

This field is the id of the buffer. If name is specified this should be 0.

TODO

TODO

TODO

TODO

TODO

TODO

This field contains the cursor's position in absolute positioning.

This field contains the number of the line where the cursor is located. This field is one based.

This field contains the number of the column where the cursor is located. This field is one based.

This field contains the x position measured with unwrapped lines.

This field contains the y position measured with unwrapped lines.

This field contains the x position measured with wrapped lines.

This field contains the y position measured with wrapped lines.

This field contains the cursor's position in absolute positioning.

This field contains the number of the line where the cursor is located. This field is one based.

This field contains the number of the column where the cursor is located. This field is one based.

struct {
};
struct {
};
struct {
};

The type field determines the coordinate system of the seek operation.

The pos field specified the pos when the seek is in absolute position.

For xy coordinate seeks, rounding down means that any x in the box of the character lands on that character. For instance when clicking rounding down is the user's expected behavior. Not rounding down means that the right hand portion of the character's box, which is closer to the next character, will land on that next character. The unrounded behavior is the expected behavior when moving vertically and keeping the preferred x.

The x coordinate for xy type seeks.

The y coordinate for xy type seeks.

The line number of a line-character type seek.

The character number of a line-character type seek.

The str_start field specifies the first character in the accompanying string that corresponds with this edit.

The len field specifies the length of the string being written into the buffer.

The start field specifies the start of the range in the buffer to replace in absolute position.

The end field specifies one past the end of the range in the buffer to replace in absolute position.

This field indicates whether the Buffer_Summary describes a buffer that is open in 4coder. When this field is false the summary is referred to as a "null summary".

If this is not a null summary, this field indicates whether the buffer has finished loading.

If this is not a null summary this field is the id of the associated buffer. If this is a null summary then buffer_id is 0.

If this is not a null summary, this field contains flags describing the protection status of the buffer.

If this is not a null summary, this field specifies the size of the text in the buffer.

If this is not a null summary, this field specifies the number of lines in the buffer.

If this is not a null summary, this field specifies the file name associated to this buffer.

This field specifies the length of the file_name string.

If this is not a null summary, this field specifies the name of the buffer.

This field specifies the length of the buffer_name string.

This field indicates the dirty state of the buffer.

If this is not a null summary, this field indicates whether the buffer is set to lex tokens.

If this is not a null summary, this field indicates whether the buffer has up to date tokens available. If this field is false, it may simply mean the tokens are still being generated in a background task and will be available later. If that is the case, is_lexed will be true to indicate that the buffer is trying to get it's tokens up to date.

If this is not a null summary, this field specifies the id of the command map for this buffer.

If this is not a null summary, this field indicates whether the buffer 'prefers' wrapped lines.

This field indicates whether the View_Summary describes a view that is open in 4coder. When this field is false the summary is referred to as a "null summary".

If this is not a null summary, this field is the id of the associated view. If this is a null summary then view_id is 0.

If this is not a null summary, then this is the id of the buffer this view currently sees.

If this is not a null summary, this field contains flags describing the protection status of the view.

If this is not a null summary, this describes the position of the cursor.

If this is not a null summary, this describes the position of the mark.

If this is not a null summary, this is the x position that is maintained in vertical navigation.

If this is not a null summary, this specifies the height of a line rendered in the view.

If this is not a null summary, this indicates that the view is set to render with unwrapped lines.

If this is not a null summary, this indicates that the view is set to highlight white space.

If this is not a null summary, this describes the screen position in which this view's buffer is displayed.

If this is not a null summary, this describes the scrolling position inside the view.

Key_Event_Data key;
Mouse_State mouse;

This field specifies whether the event was a key press or mouse event.

This field indicates that an abort event has occurred and the command needs to shut down.

This field describes a key press event.

This field describes a mouse input event.

If this event would trigger a command, this field specifies what the command would be.

This specifies the prompt portion of the drop down bar.

This specifies the main string portion of the drop down bar.

This feature is not implemented.

The style slot in the style palette.

The color in the slot.

The BatchEdit_Normal operation is always correct but does the most work if there are tokens to correct.

The BatchEdit_PreserveTokens operation is one in which none of the edits add, delete, or change any tokens. This usually applies when whitespace is being replaced with whitespace.

The pointer to the edit string buffer.

The length of the edit string buffer.

The array of edits to be applied.

The number of edits in the array.

fstr_bool char_is_slash()

This call returns non-zero if c is \ or /.

fstr_bool char_is_upper()

If c is an uppercase letter this call returns true.

fstr_bool char_is_lower()

If c is a lower letter this call returns true.

char char_to_upper()

If c is a lowercase letter this call returns the uppercase equivalent, otherwise it returns c.

char char_to_lower()

If c is an uppercase letter this call returns the lowercase equivalent, otherwise it returns c.

fstr_bool char_is_whitespace()

This call returns non-zero if c is whitespace.

fstr_bool char_is_alpha_numeric()

This call returns non-zero if c is any alphanumeric character including underscore.

fstr_bool char_is_alpha_numeric_true()

This call returns non-zero if c is any alphanumeric character no including underscore.

fstr_bool char_is_alpha()

This call returns non-zero if c is any alphabetic character including underscore.

fstr_bool char_is_alpha_true()

This call returns non-zero if c is any alphabetic character.

fstr_bool char_is_hex()

This call returns non-zero if c is any valid hexadecimal digit.

fstr_bool char_is_numeric()

This call returns non-zero if c is any valid decimal digit.

String make_string()

This call returns the String created from the parameters.

#define make_lit_string(s)

This macro takes a literal string in quotes and uses it to create a String with the correct size and memory size. Strings created this way should usually not be mutated.

#define make_fixed_width_string(s)

This macro takes a local char array with a fixed width and uses it to create an empty String with the correct size and memory size to operate on the array.

#define expand_str(s)

This macro is a helper for any calls that take a char*,integer pair to specify a string. This macro expands to both of those parameters from one String struct.

int32_t str_size()

This call returns the number of bytes before a null terminator starting at str.

String make_string_slowly()

This call makes a string by counting the number of bytes before a null terminator and treating that as the size and memory size of the string.

String substr()

This call creates a substring of str that starts with an offset from str's base, and has a fixed size. The new string uses the same underlying memory so both strings will see changes. Usually strings created this way should only go through immutable calls.

String skip_whitespace()

This call creates a substring that starts with the first non-whitespace character of str. Like other substr calls, the new string uses the underlying memory and so should usually be considered immutable.

String chop_whitespace()

This call creates a substring that ends with the last non-whitespace character of str. Like other substr calls, the new string uses the underlying memory and so should usually be considered immutable.

String skip_chop_whitespace()

This call is equivalent to calling skip_whitespace and chop_whitespace together.

String tailstr()

This call returns an empty String with underlying memory taken from the portion of str's memory that is not used.

fstr_bool match_sc()

This call returns non-zero if a and b are equivalent.

fstr_bool match_cs()

This call returns non-zero if a and b are equivalent.

fstr_bool match_ss()

This call returns non-zero if a and b are equivalent.

fstr_bool match_part_scl()

This call is similar to a match call, except that it is permitted for a to be longer than b. In other words this call returns non-zero if b is a prefix of a.

fstr_bool match_part_cc()

This call is similar to a match call, except that it is permitted for a to be longer than b. In other words this call returns non-zero if b is a prefix of a.

fstr_bool match_part_sc()

This call is similar to a match call, except that it is permitted for a to be longer than b. In other words this call returns non-zero if b is a prefix of a.

fstr_bool match_part_cs()

This call is similar to a match call, except that it is permitted for a to be longer than b. In other words this call returns non-zero if b is a prefix of a.

fstr_bool match_part_ss()

This call is similar to a match call, except that it is permitted for a to be longer than b. In other words this call returns non-zero if b is a prefix of a.

fstr_bool match_insensitive_sc()

This call returns non-zero if a and b are equivalent under case insensitive comparison.

fstr_bool match_insensitive_cs()

This call returns non-zero if a and b are equivalent under case insensitive comparison.

fstr_bool match_insensitive_ss()

This call returns non-zero if a and b are equivalent under case insensitive comparison.

fstr_bool match_part_insensitive_scl()

This call performs the same partial matching rule as match_part under case insensitive comparison.

fstr_bool match_part_insensitive_cc()

This call performs the same partial matching rule as match_part under case insensitive comparison.

fstr_bool match_part_insensitive_sc()

This call performs the same partial matching rule as match_part under case insensitive comparison.

fstr_bool match_part_insensitive_cs()

This call performs the same partial matching rule as match_part under case insensitive comparison.

fstr_bool match_part_insensitive_ss()

This call performs the same partial matching rule as match_part under case insensitive comparison.

int32_t compare_sc()

This call returns zero if a and b are equivalent, it returns negative if a sorts before b alphabetically, and positive if a sorts after b alphabetically.

int32_t compare_cs()

This call returns zero if a and b are equivalent, it returns negative if a sorts before b alphabetically, and positive if a sorts after b alphabetically.

int32_t compare_ss()

This call returns zero if a and b are equivalent, it returns negative if a sorts before b alphabetically, and positive if a sorts after b alphabetically.

int32_t find_s_char()

This call returns the index of the first occurance of character, or the size of the string if the character is not found.

int32_t find_c_chars()

This call returns the index of the first occurance of a character in the characters array, or the size of the string if no such character is not found.

int32_t find_s_chars()

This call returns the index of the first occurance of a character in the characters array, or the size of the string if no such character is not found.

int32_t find_substr_s()

This call returns the index of the first occurance of the seek substring in str or the size of str if no such substring in str is found.

int32_t find_substr_insensitive_s()

This call acts as find_substr under case insensitive comparison.

fstr_bool has_substr_s()

This call returns non-zero if the string s contains a substring equivalent to seek.

fstr_bool has_substr_insensitive_s()

This call returns non-zero if the string s contains a substring equivalent to seek under case insensitive comparison.

int32_t copy_fast_unsafe_cs()

This call performs a copy from the src string to the dest buffer. The copy does not stop until src.size characters are coppied. There is no safety against overrun so dest must be large enough to contain src. The null terminator is not written to dest. This call returns the number of bytes coppied to dest.

fstr_bool copy_partial_ss()

This call performs a copy from the src string to the dest string. The memory_size of dest is checked if the entire copy cannot be performed, as many bytes as possible are coppied to dest. This call returns non-zero if the entire string is coppied to dest.

void copy_ss()

This call performs a copy from src to dest equivalent to copy_checked.

void copy_sc()

This call performs a copy from src to dest equivalent to copy_partial.

fstr_bool append_partial_ss()

This call attemps to append as much of src into the space in dest's underlying memory as possible. If the entire string is appended the call returns non-zero.

fstr_bool append_ss()

This call is equivalent to append_partial.

fstr_bool append_sc()

This call is equivalent to append_partial.

fstr_bool terminate_with_null()

This call attemps to append a null terminator onto str without effecting the size of str. This is usually called when the time comes to pass the the string to an API that requires a null terminator. This call returns non-zero if there was a spare byte in the strings underlying memory.

fstr_bool append_padding()

This call pads out dest so that it has a size of target_size by appending the padding character c until the target size is achieved. This call returns non-zero if dest does not run out of space in the underlying memory.

void replace_char()

This call replaces all occurances of character in str with another character.

void to_lower_ss()

Rewrites the string in src into dst. src and dst should not overlap with the exception that src and dst may be exactly equal in order to convert the string in place.

void to_lower_s()

This version of to_lower converts str to lowercase in place.

void to_upper_ss()

Rewrites the string in src into dst. src and dst should not overlap with the exception that src and dst may be exactly equal in order to convert the string in place.

void to_upper_s()

This version of to_upper converts str to uppercase in place.

int32_t int_to_str_size()

This call returns the number of bytes required to represent x as a string.

fstr_bool int_to_str()

This call writes a string representation of x into dest. If there is enough space in dest this call returns non-zero.

fstr_bool append_int_to_str()

This call appends a string representation of x onto dest. If there is enough space in dest this call returns non-zero.

int32_t u64_to_str_size()

This call returns the number of bytes required to represent x as a string.

fstr_bool u64_to_str()

This call writes a string representation of x into dest. If there is enough space in dest this call returns non-zero.

fstr_bool append_u64_to_str()

This call appends a string representation of x onto dest. If there is enough space in dest this call returns non-zero.

int32_t float_to_str_size()

This call returns the number of bytes required to represent x as a string.

fstr_bool append_float_to_str()

This call writes a string representation of x into dest. If there is enough space in dest this call returns non-zero.

fstr_bool float_to_str()

This call appends a string representation of x onto dest. If there is enough space in dest this call returns non-zero.

fstr_bool str_is_int_s()

If str is a valid string representation of an integer, this call returns non-zero.

int32_t str_to_int_s()

If str represents a valid string representation of an integer, this call will return the integer represented by the string. Otherwise this call returns zero.

int32_t hexchar_to_int()

If c is a valid hexadecimal digit [0-9a-fA-F] this call returns the value of the integer value of the digit. Otherwise the return is some nonsense value.

char int_to_hexchar()

If x is in the range [0,15] this call returns the equivalent lowercase hexadecimal digit. Otherwise the return is some nonsense value.

uint32_t hexstr_to_int()

This call interprets str has a hexadecimal representation of an integer and returns the represented integer value.

fstr_bool color_to_hexstr()

This call fills s with the hexadecimal representation of the color. If there is enough memory in s to represent the color this call returns non-zero.

fstr_bool hexstr_to_color()

This call interprets s as a color and writes the 32-bit integer representation into out.

int32_t reverse_seek_slash()

This call searches for a slash in str by starting at the end and going backwards.

String front_of_directory()

This call returns a substring of dir containing only the file name or folder name furthest to the right in the directory.

String path_of_directory()

This call returns a substring of dir containing the whole path except for the final file or folder name.

fstr_bool set_last_folder_ss()

This call deletes the last file name or folder name in the dir string and appends the new provided one. If there is enough memory in dir this call returns non-zero.

String file_extension()

This call returns a substring containing only the file extension of the provided filename.

fstr_bool remove_extension()

This call attemps to delete a file extension off the end of a filename. This call returns non-zero on success.

fstr_bool remove_last_folder()

This call attemps to delete a folder or filename off the end of a path string. This call returns non-zero on success.

fstr_bool string_set_match()

This call tries to see if str matches any of the strings in str_set. If there is a match the call succeeds and returns non-zero. The matching rule is equivalent to the matching rule for match.

Cpp_Get_Token_Result cpp_get_token()

A Cpp_Get_Token_Result struct is returned containing the index of a token and a flag indicating whether the pos is contained in the token or in whitespace after the token.

This call performs a binary search over all of the tokens looking for the token that contains the specified position. If the position is in whitespace between the tokens, the returned token index is the index of the token immediately before the provided position. The returned index can be -1 if the position is before the first token.

Cpp_Lex_Result cpp_lex_step()

This call is the primary interface of the lexing system. It is quite general so it can be used in a lot of different ways. I will explain the general rules first, and then give some examples of common ways it might be used.

First a lexing state, Cpp_Lex_Data, must be initialized. The file to lex must be read into N contiguous chunks of memory. An output Cpp_Token_Array must be allocated and initialized with the appropriate count and max_count values. Then each chunk of the file must be passed to cpp_lex_step in order using the same lexing state for each call. Every time a call to cpp_lex_step returns LexResult_NeedChunk, the next call to cpp_lex_step should use the next chunk. If the return is some other value, the lexer hasn't finished with the current chunk and it sopped for some other reason, so the same chunk should be used again in the next call.

If the file chunks contain a null terminator the lexer will return LexResult_Finished when it finds this character. At this point calling the lexer again with the same state will result in an error. If you do not have a null terminated chunk to end the file, you may instead pass the exact size in bytes of the entire file to the full_size parameter and it will automatically handle the termination of the lexing state when it has read that many bytes. If a full_size is specified and the system terminates for having seen that many bytes, it will return LexResult_Finished. If a full_size is specified and a null character is read before the total number of bytes have been read the system will still terminate as usual and return LexResult_Finished.

If the system has filled the entire output array it will return LexResult_NeedTokenMemory. When this happens if you want to continue lexing the file you can grow the token array, or switch to a new output array and then call cpp_lex_step again with the chunk that was being lexed and the new output. You can also specify a max_tokens_out which is limits how many new tokens will be added to the token array. Even if token_array_out still had more space to hold tokens, if the max_tokens_out limit is hit, the lexer will stop and return LexResult_HitTokenLimit. If this happens there is still space left in the token array, so you can resume simply by calling cpp_lex_step again with the same chunk and the same output array. Also note that, unlike the chunks which must only be replaced when the system says it needs a chunk. You may switch to or modify the output array in between calls as much as you like.

The most basic use of this system is to get it all done in one big chunk and try to allocate a nearly "infinite" output array so that it will not run out of memory. This way you can get the entire job done in one call and then just assert to make sure it returns LexResult_Finished to you:

Cpp_Lex_Data cpp_lex_data_init()

A brand new lex state ready to begin lexing a file from the beginning.

Creates a new lex state in the form of a Cpp_Lex_Data struct and returns the struct. The system needs a temporary buffer that is as long as the longest token. 4096 is usually enough but the buffer is not checked, so to be 100% bullet proof it has to be the same length as the file being lexed.

int32_t cpp_lex_data_temp_size()

This call gets the current size of the temporary buffer in the lexer state so that you can move to a new temporary buffer by copying the data over.

void cpp_lex_data_temp_read()

This call reads the current contents of the temporary buffer.

void cpp_lex_data_new_temp()

This call can be used to set a new temporary buffer for the lex state. In cases where you want to discontinue lexing, store the state, and resume later. In such a situation it may be necessary for you to free the temp buffer that was originally used to make the lex state. This call allows you to supply a new temp buffer when you are ready to resume lexing.

However the new buffer needs to have the same contents the old buffer had. To ensure this you have to use cpp_lex_data_temp_size and cpp_lex_data_temp_read to get the relevant contents of the temp buffer before you free it.

Cpp_Relex_Range cpp_get_relex_range()

Cpp_Relex_Data cpp_relex_init()

Returns a partially initialized relex state.

This call does the first setup step of initializing a relex state. To finish initializing the relex state you must tell the state about the positioning of the first chunk it will be fed. There are two methods of doing this, the direct method is with cpp_relex_declare_first_chunk_position, the method that is often more convenient is with cpp_relex_is_start_chunk. If the file is not chunked the second step of initialization can be skipped.

int32_t cpp_relex_start_position()

Returns the first position in the file the relexer wants to read. This is usually a position slightly earlier than the start_pos provided as the edit range.

After doing the first stage of initialization this call is useful for figuring out what chunk of the file to feed to the lexer first. It should be a chunk that contains the position returned by this call.

void cpp_relex_declare_first_chunk_position()

To initialize the relex system completely, the system needs to know how the characters in the first file line up with the file's absolute layout. This call declares where the first chunk's start position is in the absolute file layout, and the system infers the alignment from that. For this method to work the starting position of the relexing needs to be inside the first chunk. To get the relexers starting position call cpp_relex_start_position.

int32_t cpp_relex_is_start_chunk()

Returns non-zero if the passed in chunk should be used as the first chunk for lexing.

With this method, once a state is initialized, each chunk can be fed in one after the other in the order they appear in the absolute file layout. When this call returns non-zero it means that the chunk that was passed in on that call should be used in the first call to cpp_relex_step. If, after trying all of the chunks, they all return zero, pass in NULL for chunk and 0 for chunk_size to tell the system that all possible chunks have already been tried, and then use those values again in the one and only call to cpp_relex_step.

Cpp_Lex_Result cpp_relex_step()

When a file has already been lexed, and then it is edited in a small local way, rather than lexing the new file all over again, cpp_relex_step can try to find just the range of tokens that need to be updated and fix them in.

First the lex state must be initialized (cpp_relex_init). Then one or more calls to cpp_relex_step will start editing the array and filling out the relex_array. The return value of cpp_relex_step indicates whether the relex was successful or was interrupted and if it was interrupted, what the system needs to resume.

LexResult_Finished indicates that the relex engine finished successfully.

LexResult_NeedChunk indicates that the system needs the next chunk of the file.

LexResult_NeedTokenMemory indicates that the relex_array has reached capacity, and that it needs to be extended if it is going to continue. Sometimes in this case it is better to stop and just lex the entire file normally, because there are a few cases where a small local change effects a long range of the lexers output.

The relex operation can be closed in one of two ways. If the LexResult_Finished value has been returned by this call, then to complete the edits to the array make sure the original array has enough capacity to store the final result by calling cpp_relex_get_new_count. Then the operation can be finished successfully by calling cpp_relex_complete.

Whether or not the relex process finished with LexResult_Finished the process can be finished by calling cpp_relex_abort, which puts the array back into it's original state. No close is necessary if getting the original array state back is not necessary.

int32_t cpp_relex_get_new_count()

After getting a LexResult_Finished from cpp_relex_step, this call can be used to get the size the new array will have. If the original array doesn't have enough capacity to store the new array, it's capacity should be increased before passing to cpp_relex_complete.

void cpp_relex_complete()

After getting a LexResult_Finished from cpp_relex_step, and ensuring that array has a large enough capacity by calling cpp_relex_get_new_count, this call does the necessary replacement of tokens in the array to make it match the new file.

void cpp_relex_abort()

After the first call to cpp_relex_step, the array's contents may have been changed, this call assures the array is in it's original state. After this call the relex state is dead.

Cpp_Token_Array cpp_make_token_array()

An empty Cpp_Token_Array with memory malloc'd for storing tokens.

This call allocates a Cpp_Token_Array with malloc for use in other convenience functions. Stacks that are not allocated this way should not be used in the convenience functions.

void cpp_free_token_array()

This call frees a Cpp_Token_Array.

void cpp_resize_token_array()

This call allocates a new memory chunk and moves the existing tokens in the array over to the new chunk.

void cpp_lex_file()

Lexes an entire file and manages the interaction with the lexer system so that it is quick and convenient to lex files.

enum Cpp_Token_Type;

A Cpp_Token_Type classifies a token to make parsing easier. Some types are not actually output by the lexer, but exist because parsers will also make use of token types in their own output.