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

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

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. If the file does not exist, zero is returned. 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. If the file does not exist, zero is returned. 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(ti_var_t slot)

Frees an open variable slot.

Returns

Zero if closing failed.

char *ti_Detect(void **vat_ptr, const char *detect_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.

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

char *var_name;
void *vat_ptr = NULL;

while ((var_name = ti_Detect(&vat_ptr, "my_data")))
{
    // do something with var_name or vat_ptr
}

Note

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

Parameters

  • vat_ptr – Current offset in the VAT.

  • detect_string – String to search for (NULL to search for all).

char *ti_DetectVar(void **vat_ptr, const char *detect_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.

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

char *var_name;
void *vat_ptr = NULL;

while ((var_name = ti_DetectVar(&vat_ptr, "my_data", TI_PRGM_TYPE)))
{
    // do something with var_name or vat_ptr
}

Note

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

Parameters

  • vat_ptr – Current offset in the VAT.

  • detect_string – String to search for (NULL to search for all).

  • var_type – Type of variable to detect.

char *ti_DetectAny(void **vat_ptr, const char *detect_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.

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

uint8_t var_type;
char *var_name;
void *vat_ptr = NULL;

while ((var_name = ti_DetectAny(&vat_ptr, "my_data", &var_type)))
{
    if (var_type == TI_PRGM_TYPE || var_type == TI_PPRGM_TYPE)
    {
        // do something with var_name or vat_ptr
    }
}

Note

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

Parameters

  • vat_ptr – Current offset in the VAT.

  • detect_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, 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, 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(char c, 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(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, 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(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(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(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, 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(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, 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, 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(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(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, 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, 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(ti_var_t var_type, const char *name, const 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(ti_var_t var_type_to, void *to, ti_var_t var_type_from, const 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(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.