authorgravatar for r00ster91@proton.meWooster <r00ster91@proton.me> 2022-08-14 21:39:53+02:00
committergravatar for r00ster91@proton.meWooster <r00ster91@proton.me> 2022-08-14 21:39:53+02:00
logd130d09e2b9149380609fe43bd83553650d50c8c
tree159241255aa50fd3abd46dbcf84949ef6aeb1113
parent02893d80cf013b14708d2262e9ecf0037cf6b3f2

docs: add more docs

And improve some existing docs.

1 files changed, 26 insertions(+), 11 deletions(-)

lib/std/ascii.zig+26-11
......@@ -1,16 +1,18 @@
1// Does NOT look at the locale the way C89's toupper(3), isspace() et cetera does.
2// I could have taken only a u7 to make this clear, but it would be slower
3// It is my opinion that encodings other than UTF-8 should not be supported.
4//
5// (and 128 bytes is not much to pay).
6// Also does not handle Unicode character classes.
7//
8// https://upload.wikimedia.org/wikipedia/commons/thumb/c/cf/USASCII_code_chart.png/1200px-USASCII_code_chart.png
1//! The 7-bit [ASCII](https://en.wikipedia.org/wiki/ASCII) character encoding standard.
2//!
3//! This is not to be confused with the 8-bit [extended ASCII](https://en.wikipedia.org/wiki/Extended_ASCII) character encoding.
4//!
5//! Even though this module concerns itself with 7-bit ASCII,
6//! functions use `u8` as the type instead of `u7` for convenience and compatibility.
7//! Characters outside of the 7-bit range are gracefully handled (e.g. by returning `false`).
8//!
9//! See also: https://en.wikipedia.org/wiki/ASCII#Character_set
910
1011const std = @import("std");
1112
12/// Contains constants for the C0 control codes of the ASCII encoding.
13/// https://en.wikipedia.org/wiki/C0_and_C1_control_codes
13/// The C0 control codes of the ASCII encoding.
14///
15/// See also: https://en.wikipedia.org/wiki/C0_and_C1_control_codes and `is_control`.
1416pub const control_code = struct {
1517 /// Null.
1618 pub const nul = 0x00;
......@@ -237,15 +239,20 @@ pub const spaces = whitespace;
237239/// DEPRECATED: use `isHex`.
238240pub const isXDigit = isHex;
239241
242/// Returns whether the character is alphanumeric. This is case-insensitive.
240243pub fn isAlphanumeric(c: u8) bool {
241244 return (combinedTable[c] & ((@as(u8, 1) << @enumToInt(tIndex.Alpha)) |
242245 @as(u8, 1) << @enumToInt(tIndex.Digit))) != 0;
243246}
244247
248/// Returns whether the character is alphabetic. This is case-insensitive.
245249pub fn isAlphabetic(c: u8) bool {
246250 return inTable(c, tIndex.Alpha);
247251}
248252
253/// Returns whether the character is a control character.
254///
255/// See also: `control_code`.
249256pub fn isControl(c: u8) bool {
250257 return c <= control_code.us or c == control_code.del;
251258}
......@@ -259,10 +266,13 @@ pub fn isGraph(c: u8) bool {
259266 return inTable(c, tIndex.Graph);
260267}
261268
269/// Returns whether the character is lowercased.
262270pub fn isLower(c: u8) bool {
263271 return inTable(c, tIndex.Lower);
264272}
265273
274/// Returns whether the character has some graphical representation and can be printed.
275/// This also returns `true` for the space character.
266276pub fn isPrint(c: u8) bool {
267277 return inTable(c, tIndex.Graph) or c == ' ';
268278}
......@@ -271,6 +281,7 @@ pub fn isPunct(c: u8) bool {
271281 return inTable(c, tIndex.Punct);
272282}
273283
284/// Returns whether this character is included in `whitespace`.
274285pub fn isWhitespace(c: u8) bool {
275286 return inTable(c, tIndex.Space);
276287}
......@@ -289,10 +300,12 @@ test "whitespace" {
289300 }
290301}
291302
303/// Returns whether the character is uppercased.
292304pub fn isUpper(c: u8) bool {
293305 return inTable(c, tIndex.Upper);
294306}
295307
308/// Returns whether the character is a hexadecimal digit. This is case-insensitive.
296309pub fn isHex(c: u8) bool {
297310 return inTable(c, tIndex.Hex);
298311}
......@@ -306,6 +319,7 @@ pub fn isBlank(c: u8) bool {
306319 return (c == ' ') or (c == '\x09');
307320}
308321
322/// Upper-cases the character and returns it as-is if it's already upper-cased.
309323pub fn toUpper(c: u8) u8 {
310324 if (isLower(c)) {
311325 return c & 0b11011111;
......@@ -314,6 +328,7 @@ pub fn toUpper(c: u8) u8 {
314328 }
315329}
316330
331/// Lower-cases the character and returns it as-is if it's already lower-cased.
317332pub fn toLower(c: u8) u8 {
318333 if (isUpper(c)) {
319334 return c | 0b00100000;
......@@ -392,7 +407,7 @@ test "allocUpperString" {
392407 try std.testing.expectEqualStrings("ABCDEFGHIJKLMNOPQRST0234+💩!", result);
393408}
394409
395/// Compares strings `a` and `b` case insensitively and returns whether they are equal.
410/// Compares strings `a` and `b` case-insensitively and returns whether they are equal.
396411pub fn eqlIgnoreCase(a: []const u8, b: []const u8) bool {
397412 if (a.len != b.len) return false;
398413 for (a) |a_c, i| {