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,16 +1,18 @@
1// Does NOT look at the locale the way C89's toupper(3), isspace() et cetera does.1//! The 7-bit [ASCII](https://en.wikipedia.org/wiki/ASCII) character encoding standard.
2// I could have taken only a u7 to make this clear, but it would be slower2//!
3// It is my opinion that encodings other than UTF-8 should not be supported.3//! This is not to be confused with the 8-bit [extended ASCII](https://en.wikipedia.org/wiki/Extended_ASCII) character encoding.
4//4//!
5// (and 128 bytes is not much to pay).5//! Even though this module concerns itself with 7-bit ASCII,
6// Also does not handle Unicode character classes.6//! functions use `u8` as the type instead of `u7` for convenience and compatibility.
7//7//! Characters outside of the 7-bit range are gracefully handled (e.g. by returning `false`).
8// https://upload.wikimedia.org/wikipedia/commons/thumb/c/cf/USASCII_code_chart.png/1200px-USASCII_code_chart.png8//!
9//! See also: https://en.wikipedia.org/wiki/ASCII#Character_set
910
10const std = @import("std");11const std = @import("std");
1112
12/// Contains constants for the C0 control codes of the ASCII encoding.13/// The C0 control codes of the ASCII encoding.
13/// https://en.wikipedia.org/wiki/C0_and_C1_control_codes14///
15/// See also: https://en.wikipedia.org/wiki/C0_and_C1_control_codes and `is_control`.
14pub const control_code = struct {16pub const control_code = struct {
15 /// Null.17 /// Null.
16 pub const nul = 0x00;18 pub const nul = 0x00;
...@@ -237,15 +239,20 @@ pub const spaces = whitespace;...@@ -237,15 +239,20 @@ pub const spaces = whitespace;
237/// DEPRECATED: use `isHex`.239/// DEPRECATED: use `isHex`.
238pub const isXDigit = isHex;240pub const isXDigit = isHex;
239241
242/// Returns whether the character is alphanumeric. This is case-insensitive.
240pub fn isAlphanumeric(c: u8) bool {243pub fn isAlphanumeric(c: u8) bool {
241 return (combinedTable[c] & ((@as(u8, 1) << @enumToInt(tIndex.Alpha)) |244 return (combinedTable[c] & ((@as(u8, 1) << @enumToInt(tIndex.Alpha)) |
242 @as(u8, 1) << @enumToInt(tIndex.Digit))) != 0;245 @as(u8, 1) << @enumToInt(tIndex.Digit))) != 0;
243}246}
244247
248/// Returns whether the character is alphabetic. This is case-insensitive.
245pub fn isAlphabetic(c: u8) bool {249pub fn isAlphabetic(c: u8) bool {
246 return inTable(c, tIndex.Alpha);250 return inTable(c, tIndex.Alpha);
247}251}
248252
253/// Returns whether the character is a control character.
254///
255/// See also: `control_code`.
249pub fn isControl(c: u8) bool {256pub fn isControl(c: u8) bool {
250 return c <= control_code.us or c == control_code.del;257 return c <= control_code.us or c == control_code.del;
251}258}
...@@ -259,10 +266,13 @@ pub fn isGraph(c: u8) bool {...@@ -259,10 +266,13 @@ pub fn isGraph(c: u8) bool {
259 return inTable(c, tIndex.Graph);266 return inTable(c, tIndex.Graph);
260}267}
261268
269/// Returns whether the character is lowercased.
262pub fn isLower(c: u8) bool {270pub fn isLower(c: u8) bool {
263 return inTable(c, tIndex.Lower);271 return inTable(c, tIndex.Lower);
264}272}
265273
274/// Returns whether the character has some graphical representation and can be printed.
275/// This also returns `true` for the space character.
266pub fn isPrint(c: u8) bool {276pub fn isPrint(c: u8) bool {
267 return inTable(c, tIndex.Graph) or c == ' ';277 return inTable(c, tIndex.Graph) or c == ' ';
268}278}
...@@ -271,6 +281,7 @@ pub fn isPunct(c: u8) bool {...@@ -271,6 +281,7 @@ pub fn isPunct(c: u8) bool {
271 return inTable(c, tIndex.Punct);281 return inTable(c, tIndex.Punct);
272}282}
273283
284/// Returns whether this character is included in `whitespace`.
274pub fn isWhitespace(c: u8) bool {285pub fn isWhitespace(c: u8) bool {
275 return inTable(c, tIndex.Space);286 return inTable(c, tIndex.Space);
276}287}
...@@ -289,10 +300,12 @@ test "whitespace" {...@@ -289,10 +300,12 @@ test "whitespace" {
289 }300 }
290}301}
291302
303/// Returns whether the character is uppercased.
292pub fn isUpper(c: u8) bool {304pub fn isUpper(c: u8) bool {
293 return inTable(c, tIndex.Upper);305 return inTable(c, tIndex.Upper);
294}306}
295307
308/// Returns whether the character is a hexadecimal digit. This is case-insensitive.
296pub fn isHex(c: u8) bool {309pub fn isHex(c: u8) bool {
297 return inTable(c, tIndex.Hex);310 return inTable(c, tIndex.Hex);
298}311}
...@@ -306,6 +319,7 @@ pub fn isBlank(c: u8) bool {...@@ -306,6 +319,7 @@ pub fn isBlank(c: u8) bool {
306 return (c == ' ') or (c == '\x09');319 return (c == ' ') or (c == '\x09');
307}320}
308321
322/// Upper-cases the character and returns it as-is if it's already upper-cased.
309pub fn toUpper(c: u8) u8 {323pub fn toUpper(c: u8) u8 {
310 if (isLower(c)) {324 if (isLower(c)) {
311 return c & 0b11011111;325 return c & 0b11011111;
...@@ -314,6 +328,7 @@ pub fn toUpper(c: u8) u8 {...@@ -314,6 +328,7 @@ pub fn toUpper(c: u8) u8 {
314 }328 }
315}329}
316330
331/// Lower-cases the character and returns it as-is if it's already lower-cased.
317pub fn toLower(c: u8) u8 {332pub fn toLower(c: u8) u8 {
318 if (isUpper(c)) {333 if (isUpper(c)) {
319 return c | 0b00100000;334 return c | 0b00100000;
...@@ -392,7 +407,7 @@ test "allocUpperString" {...@@ -392,7 +407,7 @@ test "allocUpperString" {
392 try std.testing.expectEqualStrings("ABCDEFGHIJKLMNOPQRST0234+💩!", result);407 try std.testing.expectEqualStrings("ABCDEFGHIJKLMNOPQRST0234+💩!", result);
393}408}
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.
396pub fn eqlIgnoreCase(a: []const u8, b: []const u8) bool {411pub fn eqlIgnoreCase(a: []const u8, b: []const u8) bool {
397 if (a.len != b.len) return false;412 if (a.len != b.len) return false;
398 for (a) |a_c, i| {413 for (a) |a_c, i| {