general.h

Go to the documentation of this file.

 
 
/*
 * general.h
 *
 *  Created on: Feb 19, 2022
 *      Author: micahbly
 */
 
// This is a cut-down, semi-API-compatible version of the OS/f general.c file from Lich King (Foenix)
// adapted for Foenix F256 Jr starting November 29, 2022
// Adapted for F256jr/k E fpga builds from F256jr/k version of FileManager starting June 2, 2024
// Debug-related functionality extracted to debug.h/.c July 2024
// adapted (back-ported) for A2560K starting Dec 26, 2024
 
 
#ifndef GENERAL_H_
#define GENERAL_H_
 
 
/* about this class
 *
 *
 *
 *** things this class needs to be able to do
 * various utility functions that any app could find useful.
 * intended to be re-usable across apps, with at most minimal differences.
 * this file should contain only cross-platform code. platform-specific code should go into general_[platformname].h/.c
 *
 *** things objects of this class have
 *
 *
 */
 
 
/*****************************************************************************/
/*                                Includes                                   */
/*****************************************************************************/
 
// project includes
//#include "text.h"
 
// C includes
#include <stdint.h>
#include <stdbool.h>
#include <stdlib.h>
 
// A2560 includes
#include "a2560k.h"
 
 
/*****************************************************************************/
/*                            Macro Definitions                              */
/*****************************************************************************/
 
 
 
/*****************************************************************************/
/*                               Enumerations                                */
/*****************************************************************************/
 
 
 
/*****************************************************************************/
/*                                 Structs                                   */
/*****************************************************************************/
 
typedef struct Coordinate
{
    uint8_t x;
    uint8_t y;
} Coordinate;
 
/*****************************************************************************/
/*                             Global Variables                              */
/*****************************************************************************/
 
 
/*****************************************************************************/
/*                       Public Function Prototypes                          */
/*****************************************************************************/
 
 
 
// **** WORD-WRAP UTILITIES *****
 
 
 
 
 
// **** MATH UTILITIES *****
 
int32_t General_Round(double the_float);
 
 
 
 
// **** NUMBER<>STRING UTILITIES *****
 
// convert a file size in bytes to a human readable format using "10 bytes", "1.4 kb", "1 MB", etc. 
//   NOTE: formatted_file_size string must have been allocated before passing here
void General_MakeFileSizeReadable(unsigned long size_in_bytes, char* formatted_file_size);
 
 
 
 
 
 
// **** MISC STRING UTILITIES *****
 
bool General_StrToLower(char* the_string);
 
uint8_t General_ToLower(uint8_t the_char);
 
char* General_StrlcpyWithAlloc(const char* src, size_t max_len);
 
int16_t General_Strlcpy(char* dst, const char* src, size_t max_len);
 
int16_t General_Strlcat(char* dst, const char* src, size_t max_len);
 
int16_t General_Strncmp(const char* string_1, const char* string_2, size_t max_len);
 
int16_t General_Strncasecmp(const char* string_1, const char* string_2, size_t max_len);
 
// Inspired by apple/bsd strnlen.
int16_t General_Strnlen(const char *the_string, size_t max_len);
 
 
 
 
// **** RECTANGLE UTILITIES *****
 
 
bool General_RectWithinRect(Rectangle r1, Rectangle r2);
 
// test if 2 rectangles intersect
bool General_RectIntersect(struct Rectangle r1, struct Rectangle r2);
 
// test if a point is within a rectangle
bool General_PointInRect(int16_t x, int16_t y, Rectangle r);
 
// Position one rect within the bounds of another. Horizontally: centers the hero rect within the left/right of the frame rect; Vertically: centers or or puts at 25% line
// put the frame coords into the frame_rect, and the object to be centered into the hero_rect. ON return, the frame rect will hold the coords to be used.
void General_CenterRectWithinRect(Rectangle* the_frame_rect, Rectangle* the_hero_rect, bool at_25_percent_v);
 
void General_CopyRect(Rectangle* r1, Rectangle* r2);
 
int16_t General_CalculateRectDifference(Rectangle* r1, Rectangle* r2, Rectangle* diff_r1, Rectangle* diff_r2, Rectangle* diff_r3, Rectangle* diff_r4);
 
bool General_CalculateRectIntersection(Rectangle* r1, Rectangle* r2, Rectangle* intersect_r);
 
 
 
 
 
// **** FILENAME AND FILEPATH UTILITIES *****
 
 
 
// // allocate and return  the portion of the path passed, minus the filename. In other words: return a path to the parent file.
// // calling method must free the string returned
// char* General_ExtractPathToParentFolderWithAlloc(const char* the_file_path);
 
// // allocate and return the filename portion of the path passed.
// // calling method must free the string returned
// char* General_ExtractFilenameFromPathWithAlloc(const char* the_file_path);
 
// populates the passed string by safely combining the passed file path and name, accounting for cases where path is a disk root
void General_CreateFilePathFromFolderAndFile(char* the_combined_path, char* the_folder_path, char* the_file_name);
 
char* General_NamePart(const char* the_file_path);
 
char* General_PathPart(const char* the_file_path);
 
bool General_ExtractFileExtensionFromFilename(const char* the_file_name, char* the_extension);
 
bool General_ExtractCoreFilename(const char* the_file_name, char* the_core_part);
 
 
 
 
// **** TIME UTILITIES *****
 
 
void General_DelayTicks(int32_t ticks);
 
void General_DelaySeconds(uint16_t seconds);
 
 
 
// **** USER INPUT UTILITIES *****
 
// Wait for one character from the keyboard and return it
char General_GetChar(void);
 
 
 
 
 
// **** MISC UTILITIES *****
 
 
uint32_t General_ByteSwapLong(uint32_t long_needing_swap);
 
// get random number between 1 and the_range + 1
// must have seeded the number generator first
// if passed 0, returns 0.
uint16_t General_GetRandom(uint16_t the_range);
 
 
 
#endif /* GENERAL_H_ */