fileioc.h

#include <fileioc.h>

The fileioc library is used for writing and reading program data to files. File support is implemented with the use of AppVars. Additionally, the library supports accessing program data and various OS variable manipulation.

API Documentation

API Documentation 

fileioc implements OS variable access routines.

Author: Matt “MateoConLechuga” Waltz

Defines

TI_PRGM_TYPE: Normal unprotect program type.

TI_PPRGM_TYPE: Normal protected program type.

TI_TPRGM_TYPE: Normal temporary program type.

TI_APPVAR_TYPE: AppVar type.

TI_STRING_TYPE: String type.

TI_EQU_TYPE: Equation type.

TI_MAX_SIZE: Maximum object size in bytes

ti_MallocReal()

Allocates space for a real variable.

Returns: Pointer to variable.

ti_MallocCplx()

Allocates space for a complex variable.

Returns: Pointer to variable.

ti_MallocString(len)

Allocates space for a string variable.

Parameters

len – Length of string.

Returns

Pointer to variable.

ti_MallocList(dim)

Allocates space for a list variable.

Parameters

dim – Dimension of list.

Returns

Pointer to variable.

ti_MallocMatrix(rows, cols)

Allocates space for a matrix variable.

Parameters

rows – Rows in matrix.
cols – Columns in matrix.

Returns

Pointer to variable.

ti_MallocCplxList(dim)

Allocates space for a complex list variable.

Parameters

dim – Dimension of complex list.

Returns

Pointer to variable.

ti_MallocEqu(len)

Allocates space for an equation variable.

Parameters

len – Length of equation variable.

Returns

Pointer to variable.

Typedefs

typedef uint8_t ti_var_t: Variable slot type.

Functions

void ti_CloseAll(void): Closes all open slots.

Warning

Call before you use any variable functions

ti_var_t ti_Open(const char *name, const char *mode)

Opens a file.

An AppVar is used as default file storage.

Note

If there isn’t enough memory to create the variable, or a slot isn’t open, zero (0) is returned

Parameters

name – Name of file to open
mode –
“r” - Opens a file for reading. The file must exist. Keeps file in archive if in archive.

”w” - Creates an empty file for writing. Overwrites file if already exists.

”a” - Appends to a file. Writing operations, append data at the end of the file. The file is created if it does not exist.

”r+” - Opens a file to update both reading and writing. The file must exist. Moves file from archive to RAM if in archive.

”w+” - Creates an empty file for both reading and writing. Overwrites file if already exists.

”a+” - Opens a file for reading and appending. Moves file from archive to RAM if in archive. Created if it does not exist.

Returns

Slot variable

ti_var_t ti_OpenVar(const char *varname, const char *mode, uint8_t type)

Opens a variable

Can open any type of program or appvar variable

Note

If there isn’t enough memory to create the variable, or a slot isn’t open, zero (0) is returned

Parameters

varname – Name of variable to open
mode –
“r” - Opens a file for reading. The file must exist. Keeps file in archive if in archive.

”w” - Creates an empty file for writing. Overwrites file if already exists.

”a” - Appends to a file. Writing operations, append data at the end of the file. The file is created if it does not exist.

”r+” - Opens a file to update both reading and writing. The file must exist. Moves file from archive to RAM if in archive.

”w+” - Creates an empty file for both reading and writing. Overwrites file if already exists.

”a+” - Opens a file for reading and appending. Moves file from archive to RAM if in archive. Created if it does not exist.
type – Specifies the type of variable to open

Returns

Slot variable

int ti_Close(const ti_var_t slot)

Frees an open variable slot.

Returns: Zero if closing failed.

char *ti_Detect(void **curr_search_posistion, const char *detection_string)

Returns the name of the file(s) that contains the string as the first part of the variable; which can then be used with ti_Open and other functions.

seach_pos should be set to NULL to begin a search, and is updated with each call.

char *var_name;
uint8_t *search_pos = NULL;
while((var_name = ti_Detect(&search_pos, "my_data")) != NULL) {
  ...do something with the name or search_pos...
}

Note

If the return value is NULL, there are no more variables to find.

Parameters

curr_search_posistion – Current offset in the VAT.
detection_string – String to search for (NULL to search for all).

char *ti_DetectVar(void **curr_search_posistion, const char *detection_string, uint8_t var_type)

Returns the name of the file(s) that contains the string as the first part of the variable; which can then be used with ti_OpenVar and other functions.

seach_pos should be set to NULL to begin a search, and is updated with each call.

char *var_name;
uint8_t *search_pos = NULL;
while((var_name = ti_DetectVar(&search_pos, "my_data", TI_PRGM_TYPE)) != NULL) {
  ...do something with the name or search_pos...
}

Note

If the return value is NULL, there are no more variables to find.

Parameters

curr_search_posistion – Current offset in the VAT.
detection_string – String to search for (NULL to search for all).
var_type – Type of variable to detect.

char *ti_DetectAny(void **curr_search_posistion, const char *detection_string, uint8_t *var_type)

Returns the name of the file(s) that contains the string as the first part of the variable; which can then be used with ti_OpenVar and other functions.

seach_pos should be set to NULL to begin a search, and is updated with each call.

char *var_name;
uint8_t *search_pos = NULL;
uint8_t type;
while((var_name = ti_DetectVar(&search_pos, "my_data", &type)) != NULL) {
  if (type == TI_PRGM_TYPE || type == TI_PPRGM_TYPE) {
   ...do something with the name or search_pos...
  }
}

Note

If the return value is NULL, there are no more variables to find.

Parameters

curr_search_posistion – Current offset in the VAT.
detection_string – String to search for (NULL to search for all).
var_type – Type of variable found.

size_t ti_Write(const void *data, size_t size, size_t count, const ti_var_t slot)

Writes to the current variable slot.

Parameters

data – Pointer to data to write.
size – Size (in bytes) of a single data chunk.
count – Number of data chunks to write to the variable slot.
slot – Variable slot to write the data to.

Returns

The number of chunks written (should be equal to count)

size_t ti_Read(void *data, size_t size, size_t count, const ti_var_t slot)

Reads from the current variable pointer.

Parameters

data – Pointer to data to read into.
size – Size (in bytes) of a single data chunk.
count – Number of data chunks to read from the variable slot.
slot – Variable slot to read the data from.

Returns

The number of chunks read (should be equal to count).

int ti_PutC(const char c, const ti_var_t slot)

Writes a character directly into the slot data pointer, and increments the offset.

Parameters

c – Character to write.
slot – Variable slot to put the character to.

Returns

The input c is returned if no error.

Returns

‘EOF’ if current offset is larger than file size, or memory isn’t large enough.

int ti_GetC(const ti_var_t slot)

Pulls a character directly from the slot data pointer, and increments the offset.

Parameters: slot – Variable slot to get the character from.
Returns: 1 byte character at the current variable offset.
Returns: ‘EOF’ if current offset is larger than file size.

int ti_Seek(int offset, unsigned int origin, const ti_var_t slot)

Seeks to an offset in the file.

Parameters

offset – Number of bytes to offest from (can be negative).
origin –
SEEK_SET (0) - Seek from beginning of file

SEEK_CUR (1) - Seek from current offset in file
SEEK_END (2) - Seek from end of file
slot – Variable slot seeking in.

Returns

‘EOF’ on seek failure.

int ti_Rewind(const ti_var_t slot)

Seeks to the start of a slot.

Same functionality as ti_Seek(0, SEEK_SET, slot)

Parameters: slot – Variable slot to rewind
Returns: ‘EOF’ on rewind failure

uint16_t ti_Tell(const ti_var_t slot)

Gets the offset in a slot.

Parameters: slot – Slot to test.
Returns: The value of the current slot offset.

uint16_t ti_GetSize(const ti_var_t slot)

Gets the size of a slot.

Parameters: slot – Slot to test.
Returns: The size of the slot variable.

int ti_Resize(size_t new_size, const ti_var_t slot)

Resizes the slot variable.

Note

The variable offset is set to the beginning of the file.

Parameters

slot – Slot to resize.
new_size – New size of slot.

Returns

Resized size on success, 0 on failure, or -1 if the slot cannot be opened.

int ti_IsArchived(const ti_var_t slot)

Tests if a slot is in the archive.

Parameters: slot – Slot to test.
Returns: 0 if the slot is not in the archive.

int ti_SetArchiveStatus(bool archived, const ti_var_t slot)

Sends the variable into either the archive or RAM if needed.

Warning

Archiving a variable can cause a garbage collection cycle. You should use ti_SetGCBehavior in the case of this event.

Parameters

archived –
True - Send to Archive.

False - Send to RAM.
slot – Slot to send.

Returns

0 if the operation fails from not enough memory.

int ti_Delete(const char *name)

Deletes an AppVar.

Parameters: name – Name of AppVar to delete.
Returns: 0 if an error is encountered.

int ti_DeleteVar(const char *varname, const uint8_t type)

Deletes a variable given the name and type.

Parameters

varname – Name of variable to delete.
type – Type of variable to delete.

Returns

0 if an error is encountered.

char *ti_GetTokenString(void **read_pointer, uint8_t *length_of_token, unsigned int *length_of_string)

Gets the string used for displaying a TI token.

Note

read_pointer is updated to the next token, depending on if it is 1 or 2 bytes in length

Parameters

length_of_string – Pointer to variable to hold length of resulting string (Can be NULL if you don’t care).
length_of_token – Pointer to variable to hold length of the token, used for determining the next read location (Can be NULL if you don’t care).
read_pointer – Address of pointer to data to read.

Returns

A pointer to string used for displaying a TI token.

void *ti_GetDataPtr(const ti_var_t slot)

Gets a pointer to the data located at the current posistion in the slot, a good way for fast reading of data.

Parameters: slot – Slot variable to get pointer of.
Returns: Pointer to variable data

void *ti_GetVATPtr(const ti_var_t slot)

Gets the VAT location of the slot.

Parameters: slot – Slot variable to get VAT location of.
Returns: VAT location of slot variable.

void ti_GetName(char *name, const ti_var_t slot)

Gets the variable name of an already opened slot.

Parameters

slot – Slot variable to get name of.
name – Buffer to store name in, allocate at least 10 bytes.

uint8_t ti_Rename(const char *old_name, const char *new_name)

Renames an AppVar.

Warning

It is potentially hazardous to rename an open AppVar. Close the AppVar before renaming.

Parameters

old_name – Old name of AppVar.
new_name – New name of AppVar.

Returns

0 if success, 1 if AppVar already exists, 2 any other error occurs.

uint8_t ti_RenameVar(const char *old_name, const char *new_name, const uint8_t type)

Renames a variable.

Warning

It is potentially hazardous to rename an open variable. Close the variable before renaming.

Parameters

old_name – Old name of variable.
new_name – New name of variable.
type – Type of variable.

Returns

0 if success, 1 if variable already exists, 2 any other error occurs.

uint8_t ti_SetVar(const ti_var_t var_type, const char *name, void *data)

Stores data or values to an OS variable.

Parameters

var_type – Type of variable to set.
name – Pointer to name of variable.
data – Pointer to data to set.

Returns

0 if success.

uint8_t ti_StoVar(const ti_var_t var_type_to, void *to, const ti_var_t var_type_from, void *from)

Stores an OS variable to another variable.

Parameters

var_type_to – Type of variable to store to.
to – Pointer to data to store to.
var_type_from – Type of variable to get from.
from – Pointer to data to get from.

Returns

0 if success.

uint8_t ti_RclVar(const uint8_t var_type, const char *var_name, void **data_struct)

Recalls a variable.

Note

data_struct is set to the variable’s data.

Parameters

var_type – Type of variable to recall.
var_name – Pointer to name of variable to recall.
data_struct – Address of pointer to variable structure.

Returns

0 if success.

bool ti_ArchiveHasRoom(uint24_t num_bytes)

Checks to see if there is room in the archive for storing num_bytes, without needing to execute a Garbage Collect.

Parameters: num_bytes – Number of bytes to be stored to the archive.
Returns: true if the bytes can be stored to the archive without a Garbage Collect.

void ti_SetGCBehavior(void (*before)(void), void (*after)(void))

Set routines to run before and after a garbage collect would be triggered.

Note

If your program uses graphx, use gfx_End and gfx_Begin to reset graphics before, and setup graphics after the garbage collect.

Parameters

before – Routine to run before a garbage collect. NULL sets it to do nothing.
after – Routine to run following a garbage collect. NULL sets it to do nothing.

fileioc.h

API Documentation

API Documentation 