xhartae/chapters/chapter_1.h

/*
Copyright (c) 2023 : Ognjen 'xolatile' Milan Robovic

Xhartae is free software! You will redistribute it or modify it under the terms of the GNU General Public License by Free Software Foundation.
And when you do redistribute it or modify it, it will use either version 3 of the License, or (at yours truly opinion) any later version.
It is distributed in the hope that it will be useful or harmful, it really depends... But no warranty what so ever, seriously. See GNU/GPLv3.
*/

#ifndef CHAPTER_1_HEADER
#define CHAPTER_1_HEADER

/*
Now that you've read the chapter zero, we should get into some technical details about C programming language. This will be the most imporant chapter for people who know some
other lower level programming language, or who intuitively understand "building blocks" of some system. Below is just a simple matrix of them, 8 x 4, so you can see that there are
really 32 keywords (ANSI C standard, I dislike newer standards), and even more below we'll categorize them.

- Keywords:

	static              signed              if                  typedef
	extern              unsigned            else                enum
	const               float               for                 union
	auto                double              do                  struct
	register            char                while               return
	volatile            int                 switch              goto
	sizeof              short               case                break
	void                long                default             continue

Keywords that you should never use, under any circumstances (except for writing your own C compiler or working in embedded) are:

- register: Hint to the compiler that some variable will be used a lot, so it can be stored in CPU register, modern compilers ignore this keyword.
- volatile: Hint to the compiler that some variable may be changed by some external source. Such a cool keyword, but never use it.
- auto: It specifies automatic storage duration for local variables inside a block. Simply, variable won't exist outside {} block it's defined in.
- signed: We'll talk about types in C more, but this is always assumed, so use only 'unsigned', when you really need to.
- union: You'll have very little excuse to use unions, because they often don't go well with type checking and introduce complexity for no reason.
- goto: I'm kidding, feel free to use 'goto' statement, it's not harmful, some people just abused it to the point of it being bullied.

Keywords that you should really consider not to use in general, but only for some very specific cases:

- const: Constant qualifier sometimes tells to the compiler that a value won't be changed. Use it only to silence the compiler warnings...
- unsigned: Again, you shouldn't care if your variable is signed or unsigned, because C really likes integers, and hates naturals. We'll talk more about it.
- float: Unless you're making a game engine with GPU acceleration or neural network, I wouldn't use this type at all due to it's limitations.
- double: Well, same as 'float', but twice bigger and more precise floating point values. You'll see it being used very rarely.
- short: Use it only to silence warnings, especially those from XCB and Xlib libraries, for whatever reason (read: X11) they use million different types.
- long: Also use this only to silence warnings, because some standard library functions use this type, pure C-hating cancer...
- typedef: I don't like it at all, but this one is my personal preference, because it just introduces unneeded mental overhead when programming.
- do: It can only be used before '{', then you do the loop thing, then '}' and then 'while' statement. I prefer just to use 'for' everywhere.

Okay, now we're left with following actually useful and C-loving keywords, 18 of them, that I'll cover more:

- char: Type for storing ASCII characters, 8 bits wide, implicitly casted to 'int' in sometimes, arrays that use them are string literals.
- int:  Type for storing signed numerical values, 32 bits wide, most number literals are casted to this type, compiler will warn you for mixing types.
- void: This is a black hole, nothing can escape it.
- sizeof: Some people say this behaves like a function, but they are wrong, it's a statement. It literally does what is says, more on that later...
- static: This qualifier has several meanings, that function or variable will only be used in that file or when inside a function, that variables persists.
- extern: This qualifier is more simple, and implicit in older compilers, newer ones warn when it's not used. Something will be used outside that file.
- if: If some condition(s) are met (equal to true or non-zero value), do the thing specified in the block.
- else: With 'else' you can "bind" multiple 'if' statements, but know that you can completely avoid it, and get the same results.
- for: Very complex kind of loop statement, that leads to segmentation faults and many other memory and safety related bugs. I love to use it.
- while: Very simple king of loop statement, that leads to segmentation faults and many other memory and safety related bugs. I don't love to use it.
- switch: This statement is the most powerful in the whole C language, it's not just if-else made pretty, we'll see examples later.
- case: Used only inside 'switch' statement, it sets some number literal as an implicit label, so when the expression in 'switch' is equals it, it jumps there.
- default: Used only because C didn't force curly brackets everywhere back when it was made, but every 'switch' should have just one 'default'.
- enum: Sometimes treated as type (with 'typedef'), and always very good way to define a lot of constants, we'll talk about them more.
- struct: I really advice against using structures, but most libraries use them, so you need to know how they work. In C, they are very weak part of the language.
- return: Used in functions to return from them with or without a result (return value). It's best when function only uses it once.
- break: When inside a loop, this statement will exit the loop. In newer standards it can take simple arguments, but we'll see why that's bad.
- continue: Even more specific case, when inside a loop, this statement will skip to the end of the loop, and then continue again.

Now, of those 18 actually useful C keywords, I like to avoid 'struct', 'switch', 'case', 'default', 'while', and use (functional) 'static' and 'extern' only in order to silence
compiler warnings, 'static' inside a function is more useful. That leaves us (me) with 12 C keywords that I love, out of complete 32 keywords in ANSI C standard. However, we'll
see that sometimes is preferable to use switch statement somewhere, or while loop when for loop feels like overkill. In most real-world cases, you'll need to use some API or
library that internally used structures everywhere, so you'll need to adapt to it, we'll see examples later...

So, real men need these keywords { char, int, void, sizeof, static, if, else, for, enum, return }, and use the rest of them in order to silence compiler warnings, use some
standard library functions, clean the source code or access an API / library / header file.
*/

extern int character_is_uppercase   (char character);
extern int character_is_lowercase   (char character);
extern int character_is_digit       (char character);
extern int character_is_blank       (char character);
extern int character_is_alpha       (char character);
extern int character_is_symbol      (char character);
extern int character_is_visible     (char character);
extern int character_is_invisible   (char character);
extern int character_is_escape      (char character);
extern int character_is_underscore  (char character);
extern int character_is_hexadecimal (char character);

extern int character_compare_array (char character, char * character_array);

#endif