LIBUNIBETACODE(3)

📦 version 2.3, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 LIBUNIBETACODE — the manual, bestie edition 💖

okay so this is the page for libunibetacode from the Library Functions Manual, and I'm gonna walk you through it like we're texting at 2am. no cap, every single detail stays. let's go ✨

🌸 NAME 🌸

libunibetacode — a whole library for converting between Beta Code and Unicode, fr fr 🦋

✨ SYNOPSIS ✨

like, here's the shape of everything, verbatim:

int
ub_beta2greek (char *beta_string, int max_beta_string, char
*utf8_string, int max_utf8_string);

int
ub_beta2coptic (char *beta_string, int max_beta_string, char
*utf8_string, int max_utf8_string);

int
ub_beta2hebrew (char *beta_string, int max_beta_string, char
*utf8_string, int max_utf8_string);

int
ub_greek2beta (char *utf8_string, int max_utf8_string, char
*beta_string, int max_beta_string);

int
ub_coptic2beta (char *utf8_string, int max_utf8_string, char
*beta_string, int max_beta_string);

int
ub_hebrew2beta (char *utf8_string, int max_utf8_string, char
*beta_string, int max_beta_string);

int
ub_codept2utf8 (unsigned codept, char *utf8_bytes);

int
ub_utf82codept (char *utf8_bytes, unsigned codept);

she's giving "eight functions, one library, zero drama" 💅

👑 DESCRIPTION 👑

So. libunibetacode is a self-contained C library that converts between UTF-8 Unicode and Beta Code — and this is the Beta Code adopted by the University of California, Irvine Thesaurus Linguae Graecae (TLG) Program and the Tufts University Perseus Project, among others. Beta Code is literally just a way to encode polytonic Greek characters using plain ASCII characters. It also has some support for encoding Coptic and Hebrew. iconic behavior honestly 🎀

The libunibetacode package contains three top-level functions to convert from Beta Code to UTF-8 Unicode, and three top-level functions to convert from UTF-8 Unicode to Beta Code. periodt.

The top-level functions that go Beta Code ➡️ UTF-8 Unicode are:

  • ub_beta2greek(3) converts a Greek Beta Code input string to a UTF-8 output string.
  • ub_beta2coptic(3) converts a Coptic Beta Code input string to a UTF-8 output string.
  • ub_beta2hebrew(3) converts a Hebrew Beta Code input string to a UTF-8 output string.

The top-level functions that go UTF-8 Unicode ➡️ Beta Code are:

  • ub_greek2beta(3) converts a Greek UTF-8 input string to a Greek Beta Code output string.
  • ub_coptic2beta(3) converts a Coptic UTF-8 input string to a Coptic Beta Code output string.
  • ub_hebrew2beta(3) converts a Hebrew UTF-8 input string to a Hebrew Beta Code output string.

And, in addition:

(not me noticing the double "to to" up there — I'm keeping it exactly as written, bestie, that's the rule 🙈)

A Unicode code point is an assignment to a specific numeric value for glyphs and other entities in Unicode fonts. By convention, Unicode code points are given by their Unicode numeric values in the form U+xxxx, where "xxxx" is a string of four hexadecimal digits representing a glyph in the Unicode Basic Multilingual Plane. slay.

All of these functions are non-destructive: they will not alter the input strings that are passed to them. your data is safe, bestie 🫶

State is not preserved between calls to any of these functions. no memory, no grudges.

The Beta Code conversion functions (ub_beta2greek, ub_beta2coptic, and ub_beta2hebrew) expect the input string to contain only Beta Code sequences for Greek, Coptic, or Hebrew, respectively. Likewise, the language-specific UTF-8 to Beta Code conversion functions (ub_greek2beta, ub_coptic2beta, and ub_hebrew2beta) expect the input string to contain only UTF-8 code points that map to valid Beta Code sequences in the respective language.

The functions ub_codept2utf8 and ub_utf82codept support the entire Unicode space of U+0000 through U+10FFF. So they're not tied to one Beta Code language (Greek, Coptic, or Hebrew), which means they can complement the other functions. versatile queens 💅

libunibetacode supports the language-specific Beta Code letter and punctutation symbol mappings described in unibetacode(5). (yes, "punctutation" — verbatim, no edits, that's the whole bit ✨)

The additional capabilities described in unibetacode(5) section "EXTENSIONS FOR ASCII AND UNICODE" are not implemented. There is also no function to perform the equivalent of the standalone program unibetaprep(1). As a consequence, ub_beta2greek does not support the full Beta Code numeric sequence range beginning with '#' and followed by a decimal number. For example, the Unicode Byzantine Music Symbols having TLG Beta Code encodings of '#2000' through '#2245' (corresponding to Unicode code points U+1D000 through U+1D0F5) are not supported. so if you were hoping for those, she's not the one 😭

The three Beta Code to UTF-8 Unicode functions also do not support the Unicode code point description format of the form "\uxxxx" that beta2uni(1) supports. That limits the usefulness of ub_beta2hebrew, because the TLG Beta Code specification only contains encodings for Hebrew consonants, not for vowels or cantillation marks. A user program could use ub_codept2utf8 along with ub_beta2hebrew to fill this gap. gap-filling arc, we love to see it 🧚

Balanced double quotes are supported in ub_beta2greek and ub_beta2coptic, but the opening and closing quotation marks must appear in the same input string because state is not preserved between calls to those functions. (An input string can contain embedded newlines.) Quotation marks in ub_beta2hebrew are output as the ASCII double quote mark (").

The ub_greek2beta function will determine whether a Greek letter follows a lower-case sigma in the input UTF-8 string, and based upon that convert Greek medial and final small sigma to "s" if context will make the conversion back from Beta Code to UTF-8 unambiguous. If this is not the case, small sigma will be converted to "s1" for small medial sigma or "s2" for small final sigma. For example, if a final sigma is followed by a letter, then the final sigma will be converted to Beta Code as "s2" to ensure proper conversion back from Beta Code into UTF-8. context-aware sigma? she's a genius, your honor 👑

Note: Thesaurus Linguae Graecae and TLG are registered trademarks of the University of California.

🎀 PARAMETERS 🎀

The top-level functions described in this document take the following parameters:

  • beta_string — A null-terminated string with Beta Code sequences for the corresponding script (Greek, Coptic, or Hebrew). This string is an input for functions that convert from Beta Code to UTF-8, and an output for functions that convert from UTF-8 to Beta Code.
  • max_beta_string — The maximum size of beta_string, in bytes, to prevent accesses past the end of the array. safety first, bestie 🫶
  • utf8_string — A null-terminated string with UTF-8 Unicode sequences for the corresponding script (Greek, Coptic, or Hebrew). This string is an output for functions that convert from Beta Code to UTF-8, and an input for functions that convert from UTF-8 to Beta Code.
  • max_utf8_string — The maximum size of utf8_string, in bytes, to prevent accesses past the end of the array.
  • codept — An unsigned 32-bit Unicode code point. This is an input to ub_codept2utf8, and an output from ub_utf82codept.
  • utf8_bytes — The null-terminated UTF-8 byte string corresponding to the Unicode code point stored in codept. This is an output from ub_codept2utf8, and an input to ub_utf82codept.

🌈 UNICODE GREEK 🌈

The Greek Extended range of The Unicode Standard (U+1F00 - U+1FFF) contains 16 small and capital vowels that have identical representation in the Greek and Coptic range (U+0370 - U+03FF). These are vowels with an oxia (acute) accent in the Greek Extended range; they have equivalent glyphs with a tonos (acute) accent in the Greek and Coptic range. Because of this duplication, the use of these 16 Greek Extended glyphs is deprecated. 🚨

However — plot twist — unlike the beta2uni program, by default the function ub_beta2greek maps to those 16 deprecated code points. This was done after observing that many fonts contain consistent looking glyphs in the Unicode Greek Extended block that do not have a consistent appearance with the Greek and Coptic block. aesthetics won, honestly 💅

The choice between these two options is compiled in with a #define statement near the beginning of "ub_beta2greek.c", which is in the "src/libsrc" directory in the source distribution. To avoid conversion to these 16 deprecated code points, change the following two lines:

// #define GREEK_COMBINING beta2combining
#define GREEK_COMBINING beta2combining_alt

to this:

#define GREEK_COMBINING beta2combining
// #define GREEK_COMBINING beta2combining_alt

and then recompile the package by running "make" in the top-level package source directory. that's it. that's the whole switch. go off 🎀

⭐ RETURN VALUES ⭐

Each of the four library functions returns the number of bytes in the UTF-8 output string, not including the final null character that terminates the string. yes bestie, four, that's what it says, I'm not touching it 🙈

🦋 SAMPLES 🦋

The directory "examples" in the source distribution contains samples with mappings from Beta Code to UTF-8 and vice versa. The "genesis-1-1.beta" and "genesis-1-1.utf8" files show the Bible verse Genesis 1:1 in Koine Greek (from the Septuagint), Hebrew, and Bohairic Coptic in Beta Code and UTF-8, respectively. three languages, one verse, absolutely ate 🍓

The program "test/ublibcheck.c" in the source distribution is a sample program that calls ub_beta2greek, ub_beta2coptic, and ub_beta2hebrew to convert the above-mentioned Genesis 1:1 passage. Each of those three functions calls ub_codept2utf8 to produce its UTF-8 output. Hence this program tests all four of the top-level library functions. Once the "make install" command above has completed, the test program can be copied to another directory and compiled separately as a starting point for new software as follows:

cc ublibcheck.c -o ublibcheck -lunibetacode

copy that, run it, become the main character of your own Unicode project 🌸

💜 SEE ALSO 💜

unibetaprep(1), beta2uni(1), uni2beta(1), unibetacode(5)

🌟 AUTHOR 🌟

The unibetacode package was created by Paul Hardy. 👑

📜 LICENSE 📜

libunibetacode is Copyright © 2020 Paul Hardy.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

💀 BUGS 💀

No known bugs exist. However, all corner cases have not been tested. so like... she's flawless as far as we know, but also nobody has checked every single corner yet. vibe check pending 😭

2020 Apr 11 — that's the date and the source stamp, and the page is LIBUNIBETACODE(3) from the Library Functions Manual. mwah, love u, go convert some Greek 💖✨🦋

📦 where this page comes from