{"id":23396056,"url":"https://github.com/martin-rizzo/textfile","last_synced_at":"2025-10-07T16:58:11.529Z","repository":{"id":38949802,"uuid":"257721317","full_name":"martin-rizzo/TextFile","owner":"martin-rizzo","description":"A portable, one-header C library to easily read lines of text from files encoded in any format.","archived":false,"fork":false,"pushed_at":"2022-07-05T12:21:36.000Z","size":62,"stargazers_count":4,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-08T17:36:45.941Z","etag":null,"topics":["c","group-microlibs","header-only-library","unicode"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/martin-rizzo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-04-21T21:35:31.000Z","updated_at":"2025-03-05T01:09:01.000Z","dependencies_parsed_at":"2022-09-18T20:32:46.046Z","dependency_job_id":null,"html_url":"https://github.com/martin-rizzo/TextFile","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/martin-rizzo/TextFile","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martin-rizzo%2FTextFile","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martin-rizzo%2FTextFile/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martin-rizzo%2FTextFile/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martin-rizzo%2FTextFile/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/martin-rizzo","download_url":"https://codeload.github.com/martin-rizzo/TextFile/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martin-rizzo%2FTextFile/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278811844,"owners_count":26050181,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","group-microlibs","header-only-library","unicode"],"created_at":"2024-12-22T07:29:41.121Z","updated_at":"2025-10-07T16:58:11.499Z","avatar_url":"https://github.com/martin-rizzo.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eTextFile\u003c/h1\u003e\n\u003cp align=\"center\"\u003eA portable, header only C library to easily read lines of text from files encoded in any format.\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cimg alt=\"Platform\" src=\"https://img.shields.io/badge/platform-any-33F\"\u003e\n\u003cimg alt=\"Language\" src=\"https://img.shields.io/badge/language-C-22E\"\u003e\n\u003cimg alt=\"License\"  src=\"https://img.shields.io/github/license/martin-rizzo/TextFile?color=11D\"\u003e\n\u003cimg alt=\"Last\"     src=\"https://img.shields.io/github/last-commit/martin-rizzo/TextFile\"\u003e\n\u003c/p\u003e\n\n**TextFile** has an interface similar to fopen/fgets but transparently converts each line of text to UTF-8 from whatever the encoding of the source file is. The different end-of-line formats (win, mac, linux) are also transparently processed without any user intervention.\n\nInstallation and usage\n----------------------\nTextFile is a single header library. That is, you only need to copy the `'textfile.h'` header into any folder of your project's source tree. Then when you want to start using TextFile functions for first time, you must include the header in your code but making sure to define TEXTFILE_IMPLEMENTATION macro just before including it:\n\n```C\n    #define TEXTFILE_IMPLEMENTATION\n    #include \"textfile.h\"\n```\n\nLater if other source files in your project need to use the TextFile functions then they only must include the header as usual WITHOUT having to define the macro again.\n\nFunctions\n---------\n\n```C\n    /*== OPEN/READ/CLOSE FUNCTIONS =======================*/\n    TEXTFILE*      textfopen(const char* filename, const char* mode);\n    char*          textfgetline(TEXTFILE* textfile);\n    int            textfclose(TEXTFILE* textfile);\n    \n    /*== ENCODING DETECTION FUNCTIONS ====================*/\n    int            textfissupported(TEXTFILE* textfile);\n    TEXTF_ENCODING textfgetencoding(TEXTFILE* textfile);\n    TEXTF_EOL      textfgeteol(TEXTFILE* textfile);\n    \n    /*== COMPATIBILITY FUNCTIONS =========================*/\n    char*          textfgets(char* buffer, int bufsize, TEXTFILE* textfile);\n```\n\nDocumentation\n-------------\n\n### textfopen( )\n\nOpens the file whose path is specified in 'filename' and returns a TEXTFILE object that can be used in future read operations on this file.\n\n```C\nTEXTFILE* textfopen(const char* filename, const char* mode);\n```\n  * `filename` : The path to the file to open\n  * `mode` : A null-terminated string determining the file access mode (only the \"r\" mode is supported).\n  * Returns the pointer to a TEXTFILE object that controls the opened file or NULL if an error has ocurred\n\n--------------------------------------------------\n### textfgetline( )\n\nRead a line of text from the provided file.\n\n```C\nchar* textfgetline(TEXTFILE* textfile);\n```\n\n * `textfile` : A pointer to the TEXTFILE object that controls the file to read the data from.\n * Returns a pointer to the buffer containing the read line or `NULL` if there isn't more lines to read.\n\n-----------------------------\n### textfclose( )\n\nCloses the file associated with the provided TEXTFILE object and releases all related resources.\n\n```C\nint textfclose(TEXTFILE* textfile);\n```\n\n * `textfile` : A pointer to the TEXTFILE object that specifies the file to close.\n * Returns zero (0) if the file is successfully closed.\n\n--------------------------------------------------\n### textfissupported( )\n\nVerifies if the encoding of the provided file is supported by TextFile.\n\nIf the encoding of the opened file isn't supported then the textfgetline function will always return NULL. At the moment only ASCII, Extended-ASCII, UTF-8 and UTF-8 with BOM are supported.\n\n```C\nint textfissupported(TEXTFILE* textfile);\n```\n\n * `textfile` : A pointer to the TEXTFILE object that identifies the file opened with the textfopen function\n * Returns TRUE/1 if the encoding is supported, otherwise FALSE/0\n\n\n--------------------------------------------------\n### testfgetencoding( )\n\nReturns the detected encoding of the opened file.\n\nAlthough ASCII and Extended-ASCII encoding are supported, they aren't detected by TextFile (both are reported as TEXTF_UTF8). Since pure ASCII is a subset of UTF8-8, this would not cause any problem.\n\n```C\nTEXTF_ENCODING textfgetencoding(TEXTFILE* textfile);\n```\n\n * `textfile` : A pointer to the TEXTFILE object that identifies the file opened with the textfopen function\n * Returns one of the following encoding methods:\n\n|  encoding method              |                   description                                    |\n|-------------------------------|------------------------------------------------------------------|\n| `TEXTF_ENCODING_UTF8`         | UTF-8, ASCII, Extended-ASCII (ex:Windows-1252), ...              |\n| `TEXTF_ENCODING_UTF8_BOM`     | UTF-8 with BOM [confirmed]                                       |\n| `TEXTF_ENCODING_UTF16_LE`     | UTF-16 little-endian [guessed]                                   |\n| `TEXTF_ENCODING_UTF16_BE`     | UTF-16 big-endian [guessed]                                      |\n| `TEXTF_ENCODING_UTF16_LE_BOM` | UTF-16 with BOM, little-endian [confirmed]                       |\n| `TEXTF_ENCODING_UTF16_BE_BOM` | UTF-16 with BOM, big-endian [confirmed]                          |\n| `TEXTF_ENCODING_BINARY `      | invalid or unsupported text encoding (it's likely a binary file) |\n\n\n\n--------------------------------------------------\n### textfgeteol( )\n\nReturns the end-of-line format of the opened file.\n\n```C\nTEXTF_EOL textfgeteol(TXTFILE* textfile);\n```\n\n * `textfile` : A pointer to the TEXTFILE object that identifies the file opened with the textfopen function\n * Returns one of the following end-of-line formats:\n\n|  end-of-line format    |                   description                              |\n|------------------------|------------------------------------------------------------|\n| `TEXTF_EOL_WINDOWS`    | `\\r\\n` : MS Windows, DOS, CP/M, OS/2, Atari TOS, ...       |\n| `TEXTF_EOL_UNIX`       | `\\n`   : Linux, macOS, BeOS, Amiga, RISC OS, ...           |\n| `TEXTF_EOL_CLASSICMAC` | `\\r`   :  Classic Mac OS, C64, ZX Spectrum, Apple II, ...  |\n| `TEXTF_EOL_ACORNBBC`   | `\\n\\r` : Acorn BBC                                         |\n| `TEXTF_EOL_UNKNOWN`    |  The file is too small or it has an unsupported encoding   |\n\n\n--------------------------------------------------\n### textfgets( )\n\nThis function is for compatibility with preexistent source code using standard file access.\n\nReads characters from text file until (bufsize-1) characters have been read or either a newline or end-of-file is reached, whichever happens first.\n\n```C\nchar* textfgets(char* buffer, int bufsize, TEXTFILE* textfile)\n```\n\n * `buffer` : A pointer to the buffer of chars where the string read will be stored\n * `bufsize` : The maximum number of bytes to be copied into 'buffer' (including '\\0')\n * `textfile` : A pointer to the TEXTFILE object that identifies a file opened with the 'textfopen' function\n * Returns a pointer to 'buffer' when success or NULL when no more lines can be read\n \n\n\nExamples\n--------\n\n```C\n#include \"textfile.h\"\n\nBOOL printLinesOfText(const char* filename) {\n    TEXTFILE* textfile;\n    const char* line; int num;\n    \n    textfile = textfopen(filename, \"r\");\n    if (!textfile) { return FALSE; }\n    \n    num = 1; do {\n        line = textfgetline(textfile);\n        if (line != NULL) { printf(\"%d: %s\\n\", num++, line); }\n    } while (line != NULL);\n    \n    textfclose(textfile);\n    return TRUE;\n}\n\n```\n\nLicense\n-------\n\nCopyright (c) 2020 Martin Rizzo\n\nThis project is licensed under the MIT license.  \nSee the [LICENSE.md](\"LICENSE.md\") file for details.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartin-rizzo%2Ftextfile","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmartin-rizzo%2Ftextfile","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartin-rizzo%2Ftextfile/lists"}