From 67fd3c725e6511adf70345f0733ec0b948477a11 Mon Sep 17 00:00:00 2001 From: Bruce Hill Date: Sat, 19 Apr 2025 14:35:34 -0400 Subject: Make API documentation into YAML files and autogenerate markdown files and manpages from those. --- Makefile | 18 +- api/api.md | 4814 +++++++++++++++++++++++++++++ api/booleans.md | 30 + api/booleans.yaml | 22 + api/builtins.md | 183 ++ api/builtins.yaml | 168 + api/bytes.md | 108 + api/bytes.yaml | 104 + api/integers.md | 370 +++ api/integers.yaml | 362 +++ api/lists.md | 651 ++++ api/lists.yaml | 660 ++++ api/nums.md | 1233 ++++++++ api/nums.yaml | 978 ++++++ api/paths.md | 936 ++++++ api/paths.yaml | 875 ++++++ api/sets.md | 243 ++ api/sets.yaml | 221 ++ api/tables.md | 164 + api/tables.yaml | 155 + api/text.md | 923 ++++++ api/text.yaml | 915 ++++++ docs/booleans.md | 30 +- docs/builtins.md | 184 -- docs/bytes.md | 51 +- docs/integers.md | 392 +-- docs/lists.md | 678 +--- docs/nums.md | 1144 +------ docs/paths.md | 965 +----- docs/sets.md | 236 +- docs/tables.md | 167 +- docs/text.md | 976 +----- docs/tomo.1 | 75 - man/man1/tomo.1 | 75 + man/man3/tomo-Bool.parse.3 | 38 + man/man3/tomo-Byte.hex.3 | 36 + man/man3/tomo-Byte.is_between.3 | 40 + man/man3/tomo-Byte.parse.3 | 36 + man/man3/tomo-Byte.to.3 | 43 + man/man3/tomo-Int.abs.3 | 34 + man/man3/tomo-Int.choose.3 | 35 + man/man3/tomo-Int.clamped.3 | 36 + man/man3/tomo-Int.factorial.3 | 34 + man/man3/tomo-Int.format.3 | 35 + man/man3/tomo-Int.hex.3 | 37 + man/man3/tomo-Int.is_between.3 | 40 + man/man3/tomo-Int.is_prime.3 | 40 + man/man3/tomo-Int.next_prime.3 | 37 + man/man3/tomo-Int.octal.3 | 36 + man/man3/tomo-Int.onward.3 | 39 + man/man3/tomo-Int.parse.3 | 44 + man/man3/tomo-Int.prev_prime.3 | 37 + man/man3/tomo-Int.sqrt.3 | 36 + man/man3/tomo-Int.to.3 | 43 + man/man3/tomo-List.binary_search.3 | 41 + man/man3/tomo-List.by.3 | 35 + man/man3/tomo-List.clear.3 | 33 + man/man3/tomo-List.counts.3 | 34 + man/man3/tomo-List.find.3 | 38 + man/man3/tomo-List.first.3 | 37 + man/man3/tomo-List.from.3 | 35 + man/man3/tomo-List.has.3 | 35 + man/man3/tomo-List.heap_pop.3 | 37 + man/man3/tomo-List.heap_push.3 | 35 + man/man3/tomo-List.heapify.3 | 35 + man/man3/tomo-List.insert.3 | 45 + man/man3/tomo-List.insert_all.3 | 45 + man/man3/tomo-List.pop.3 | 47 + man/man3/tomo-List.random.3 | 35 + man/man3/tomo-List.remove_at.3 | 45 + man/man3/tomo-List.remove_item.3 | 45 + man/man3/tomo-List.reversed.3 | 34 + man/man3/tomo-List.sample.3 | 40 + man/man3/tomo-List.shuffle.3 | 34 + man/man3/tomo-List.shuffled.3 | 35 + man/man3/tomo-List.slice.3 | 39 + man/man3/tomo-List.sort.3 | 41 + man/man3/tomo-List.sorted.3 | 38 + man/man3/tomo-List.to.3 | 38 + man/man3/tomo-List.unique.3 | 34 + man/man3/tomo-Num.1_PI.3 | 18 + man/man3/tomo-Num.2_PI.3 | 18 + man/man3/tomo-Num.2_SQRTPI.3 | 18 + man/man3/tomo-Num.E.3 | 18 + man/man3/tomo-Num.INF.3 | 18 + man/man3/tomo-Num.LN10.3 | 18 + man/man3/tomo-Num.LN2.3 | 18 + man/man3/tomo-Num.LOG2E.3 | 18 + man/man3/tomo-Num.PI.3 | 18 + man/man3/tomo-Num.PI_2.3 | 18 + man/man3/tomo-Num.PI_4.3 | 18 + man/man3/tomo-Num.SQRT1_2.3 | 18 + man/man3/tomo-Num.SQRT2.3 | 18 + man/man3/tomo-Num.TAU.3 | 18 + man/man3/tomo-Num.abs.3 | 34 + man/man3/tomo-Num.acos.3 | 34 + man/man3/tomo-Num.acosh.3 | 34 + man/man3/tomo-Num.asin.3 | 34 + man/man3/tomo-Num.asinh.3 | 34 + man/man3/tomo-Num.atan.3 | 34 + man/man3/tomo-Num.atan2.3 | 35 + man/man3/tomo-Num.atanh.3 | 34 + man/man3/tomo-Num.cbrt.3 | 34 + man/man3/tomo-Num.ceil.3 | 34 + man/man3/tomo-Num.clamped.3 | 36 + man/man3/tomo-Num.copysign.3 | 35 + man/man3/tomo-Num.cos.3 | 34 + man/man3/tomo-Num.cosh.3 | 34 + man/man3/tomo-Num.erf.3 | 34 + man/man3/tomo-Num.erfc.3 | 34 + man/man3/tomo-Num.exp.3 | 34 + man/man3/tomo-Num.exp2.3 | 34 + man/man3/tomo-Num.expm1.3 | 34 + man/man3/tomo-Num.fdim.3 | 37 + man/man3/tomo-Num.floor.3 | 34 + man/man3/tomo-Num.format.3 | 35 + man/man3/tomo-Num.hypot.3 | 35 + man/man3/tomo-Num.is_between.3 | 40 + man/man3/tomo-Num.isfinite.3 | 36 + man/man3/tomo-Num.isinf.3 | 36 + man/man3/tomo-Num.j0.3 | 34 + man/man3/tomo-Num.j1.3 | 34 + man/man3/tomo-Num.log.3 | 34 + man/man3/tomo-Num.log10.3 | 34 + man/man3/tomo-Num.log1p.3 | 34 + man/man3/tomo-Num.log2.3 | 34 + man/man3/tomo-Num.logb.3 | 34 + man/man3/tomo-Num.mix.3 | 38 + man/man3/tomo-Num.near.3 | 43 + man/man3/tomo-Num.nextafter.3 | 35 + man/man3/tomo-Num.parse.3 | 36 + man/man3/tomo-Num.percent.3 | 37 + man/man3/tomo-Num.rint.3 | 36 + man/man3/tomo-Num.round.3 | 36 + man/man3/tomo-Num.scientific.3 | 35 + man/man3/tomo-Num.significand.3 | 34 + man/man3/tomo-Num.sin.3 | 34 + man/man3/tomo-Num.sinh.3 | 34 + man/man3/tomo-Num.sqrt.3 | 34 + man/man3/tomo-Num.tan.3 | 34 + man/man3/tomo-Num.tanh.3 | 34 + man/man3/tomo-Num.tgamma.3 | 34 + man/man3/tomo-Num.trunc.3 | 36 + man/man3/tomo-Num.y0.3 | 34 + man/man3/tomo-Num.y1.3 | 34 + man/man3/tomo-Path.accessed.3 | 37 + man/man3/tomo-Path.append.3 | 35 + man/man3/tomo-Path.append_bytes.3 | 35 + man/man3/tomo-Path.base_name.3 | 34 + man/man3/tomo-Path.by_line.3 | 42 + man/man3/tomo-Path.can_execute.3 | 38 + man/man3/tomo-Path.can_read.3 | 38 + man/man3/tomo-Path.can_write.3 | 38 + man/man3/tomo-Path.changed.3 | 40 + man/man3/tomo-Path.child.3 | 35 + man/man3/tomo-Path.children.3 | 35 + man/man3/tomo-Path.create_directory.3 | 34 + man/man3/tomo-Path.current_dir.3 | 26 + man/man3/tomo-Path.exists.3 | 34 + man/man3/tomo-Path.expand_home.3 | 36 + man/man3/tomo-Path.extension.3 | 41 + man/man3/tomo-Path.files.3 | 35 + man/man3/tomo-Path.from_components.3 | 38 + man/man3/tomo-Path.glob.3 | 60 + man/man3/tomo-Path.group.3 | 37 + man/man3/tomo-Path.is_directory.3 | 38 + man/man3/tomo-Path.is_file.3 | 38 + man/man3/tomo-Path.is_socket.3 | 35 + man/man3/tomo-Path.is_symlink.3 | 34 + man/man3/tomo-Path.modified.3 | 37 + man/man3/tomo-Path.owner.3 | 37 + man/man3/tomo-Path.parent.3 | 34 + man/man3/tomo-Path.read.3 | 37 + man/man3/tomo-Path.read_bytes.3 | 38 + man/man3/tomo-Path.relative_to.3 | 35 + man/man3/tomo-Path.remove.3 | 34 + man/man3/tomo-Path.resolved.3 | 38 + man/man3/tomo-Path.set_owner.3 | 36 + man/man3/tomo-Path.subdirectories.3 | 38 + man/man3/tomo-Path.unique_directory.3 | 37 + man/man3/tomo-Path.write.3 | 35 + man/man3/tomo-Path.write_bytes.3 | 35 + man/man3/tomo-Path.write_unique.3 | 38 + man/man3/tomo-Path.write_unique_bytes.3 | 38 + man/man3/tomo-Set.add.3 | 34 + man/man3/tomo-Set.add_all.3 | 34 + man/man3/tomo-Set.clear.3 | 33 + man/man3/tomo-Set.has.3 | 35 + man/man3/tomo-Set.is_subset_of.3 | 36 + man/man3/tomo-Set.is_superset_of.3 | 36 + man/man3/tomo-Set.overlap.3 | 35 + man/man3/tomo-Set.remove.3 | 34 + man/man3/tomo-Set.remove_all.3 | 34 + man/man3/tomo-Set.with.3 | 35 + man/man3/tomo-Set.without.3 | 35 + man/man3/tomo-Table.clear.3 | 33 + man/man3/tomo-Table.get.3 | 45 + man/man3/tomo-Table.get_or_set.3 | 48 + man/man3/tomo-Table.has.3 | 37 + man/man3/tomo-Table.remove.3 | 37 + man/man3/tomo-Table.set.3 | 38 + man/man3/tomo-Text.as_c_string.3 | 34 + man/man3/tomo-Text.at.3 | 35 + man/man3/tomo-Text.by_line.3 | 39 + man/man3/tomo-Text.by_split.3 | 40 + man/man3/tomo-Text.by_split_any.3 | 40 + man/man3/tomo-Text.bytes.3 | 34 + man/man3/tomo-Text.caseless_equals.3 | 40 + man/man3/tomo-Text.codepoint_names.3 | 34 + man/man3/tomo-Text.ends_with.3 | 35 + man/man3/tomo-Text.from.3 | 38 + man/man3/tomo-Text.from_bytes.3 | 34 + man/man3/tomo-Text.from_c_string.3 | 34 + man/man3/tomo-Text.from_codepoint_names.3 | 38 + man/man3/tomo-Text.from_codepoints.3 | 34 + man/man3/tomo-Text.has.3 | 37 + man/man3/tomo-Text.join.3 | 35 + man/man3/tomo-Text.left_pad.3 | 39 + man/man3/tomo-Text.lines.3 | 42 + man/man3/tomo-Text.lower.3 | 38 + man/man3/tomo-Text.middle_pad.3 | 39 + man/man3/tomo-Text.quoted.3 | 36 + man/man3/tomo-Text.repeat.3 | 35 + man/man3/tomo-Text.replace.3 | 36 + man/man3/tomo-Text.reversed.3 | 34 + man/man3/tomo-Text.right_pad.3 | 39 + man/man3/tomo-Text.slice.3 | 42 + man/man3/tomo-Text.split.3 | 38 + man/man3/tomo-Text.split_any.3 | 35 + man/man3/tomo-Text.starts_with.3 | 35 + man/man3/tomo-Text.title.3 | 39 + man/man3/tomo-Text.to.3 | 38 + man/man3/tomo-Text.translate.3 | 40 + man/man3/tomo-Text.trim.3 | 43 + man/man3/tomo-Text.upper.3 | 39 + man/man3/tomo-Text.utf32_codepoints.3 | 34 + man/man3/tomo-Text.width.3 | 39 + man/man3/tomo-Text.without_prefix.3 | 37 + man/man3/tomo-Text.without_suffix.3 | 37 + man/man3/tomo-USE_COLOR.3 | 18 + man/man3/tomo-ask.3 | 39 + man/man3/tomo-exit.3 | 34 + man/man3/tomo-fail.3 | 33 + man/man3/tomo-getenv.3 | 34 + man/man3/tomo-print.3 | 35 + man/man3/tomo-say.3 | 35 + man/man3/tomo-setenv.3 | 34 + man/man3/tomo-sleep.3 | 33 + scripts/api_gen.py | 80 + 249 files changed, 21852 insertions(+), 4880 deletions(-) create mode 100644 api/api.md create mode 100644 api/booleans.md create mode 100644 api/booleans.yaml create mode 100644 api/builtins.md create mode 100644 api/builtins.yaml create mode 100644 api/bytes.md create mode 100644 api/bytes.yaml create mode 100644 api/integers.md create mode 100644 api/integers.yaml create mode 100644 api/lists.md create mode 100644 api/lists.yaml create mode 100644 api/nums.md create mode 100644 api/nums.yaml create mode 100644 api/paths.md create mode 100644 api/paths.yaml create mode 100644 api/sets.md create mode 100644 api/sets.yaml create mode 100644 api/tables.md create mode 100644 api/tables.yaml create mode 100644 api/text.md create mode 100644 api/text.yaml delete mode 100644 docs/builtins.md delete mode 100644 docs/tomo.1 create mode 100644 man/man1/tomo.1 create mode 100644 man/man3/tomo-Bool.parse.3 create mode 100644 man/man3/tomo-Byte.hex.3 create mode 100644 man/man3/tomo-Byte.is_between.3 create mode 100644 man/man3/tomo-Byte.parse.3 create mode 100644 man/man3/tomo-Byte.to.3 create mode 100644 man/man3/tomo-Int.abs.3 create mode 100644 man/man3/tomo-Int.choose.3 create mode 100644 man/man3/tomo-Int.clamped.3 create mode 100644 man/man3/tomo-Int.factorial.3 create mode 100644 man/man3/tomo-Int.format.3 create mode 100644 man/man3/tomo-Int.hex.3 create mode 100644 man/man3/tomo-Int.is_between.3 create mode 100644 man/man3/tomo-Int.is_prime.3 create mode 100644 man/man3/tomo-Int.next_prime.3 create mode 100644 man/man3/tomo-Int.octal.3 create mode 100644 man/man3/tomo-Int.onward.3 create mode 100644 man/man3/tomo-Int.parse.3 create mode 100644 man/man3/tomo-Int.prev_prime.3 create mode 100644 man/man3/tomo-Int.sqrt.3 create mode 100644 man/man3/tomo-Int.to.3 create mode 100644 man/man3/tomo-List.binary_search.3 create mode 100644 man/man3/tomo-List.by.3 create mode 100644 man/man3/tomo-List.clear.3 create mode 100644 man/man3/tomo-List.counts.3 create mode 100644 man/man3/tomo-List.find.3 create mode 100644 man/man3/tomo-List.first.3 create mode 100644 man/man3/tomo-List.from.3 create mode 100644 man/man3/tomo-List.has.3 create mode 100644 man/man3/tomo-List.heap_pop.3 create mode 100644 man/man3/tomo-List.heap_push.3 create mode 100644 man/man3/tomo-List.heapify.3 create mode 100644 man/man3/tomo-List.insert.3 create mode 100644 man/man3/tomo-List.insert_all.3 create mode 100644 man/man3/tomo-List.pop.3 create mode 100644 man/man3/tomo-List.random.3 create mode 100644 man/man3/tomo-List.remove_at.3 create mode 100644 man/man3/tomo-List.remove_item.3 create mode 100644 man/man3/tomo-List.reversed.3 create mode 100644 man/man3/tomo-List.sample.3 create mode 100644 man/man3/tomo-List.shuffle.3 create mode 100644 man/man3/tomo-List.shuffled.3 create mode 100644 man/man3/tomo-List.slice.3 create mode 100644 man/man3/tomo-List.sort.3 create mode 100644 man/man3/tomo-List.sorted.3 create mode 100644 man/man3/tomo-List.to.3 create mode 100644 man/man3/tomo-List.unique.3 create mode 100644 man/man3/tomo-Num.1_PI.3 create mode 100644 man/man3/tomo-Num.2_PI.3 create mode 100644 man/man3/tomo-Num.2_SQRTPI.3 create mode 100644 man/man3/tomo-Num.E.3 create mode 100644 man/man3/tomo-Num.INF.3 create mode 100644 man/man3/tomo-Num.LN10.3 create mode 100644 man/man3/tomo-Num.LN2.3 create mode 100644 man/man3/tomo-Num.LOG2E.3 create mode 100644 man/man3/tomo-Num.PI.3 create mode 100644 man/man3/tomo-Num.PI_2.3 create mode 100644 man/man3/tomo-Num.PI_4.3 create mode 100644 man/man3/tomo-Num.SQRT1_2.3 create mode 100644 man/man3/tomo-Num.SQRT2.3 create mode 100644 man/man3/tomo-Num.TAU.3 create mode 100644 man/man3/tomo-Num.abs.3 create mode 100644 man/man3/tomo-Num.acos.3 create mode 100644 man/man3/tomo-Num.acosh.3 create mode 100644 man/man3/tomo-Num.asin.3 create mode 100644 man/man3/tomo-Num.asinh.3 create mode 100644 man/man3/tomo-Num.atan.3 create mode 100644 man/man3/tomo-Num.atan2.3 create mode 100644 man/man3/tomo-Num.atanh.3 create mode 100644 man/man3/tomo-Num.cbrt.3 create mode 100644 man/man3/tomo-Num.ceil.3 create mode 100644 man/man3/tomo-Num.clamped.3 create mode 100644 man/man3/tomo-Num.copysign.3 create mode 100644 man/man3/tomo-Num.cos.3 create mode 100644 man/man3/tomo-Num.cosh.3 create mode 100644 man/man3/tomo-Num.erf.3 create mode 100644 man/man3/tomo-Num.erfc.3 create mode 100644 man/man3/tomo-Num.exp.3 create mode 100644 man/man3/tomo-Num.exp2.3 create mode 100644 man/man3/tomo-Num.expm1.3 create mode 100644 man/man3/tomo-Num.fdim.3 create mode 100644 man/man3/tomo-Num.floor.3 create mode 100644 man/man3/tomo-Num.format.3 create mode 100644 man/man3/tomo-Num.hypot.3 create mode 100644 man/man3/tomo-Num.is_between.3 create mode 100644 man/man3/tomo-Num.isfinite.3 create mode 100644 man/man3/tomo-Num.isinf.3 create mode 100644 man/man3/tomo-Num.j0.3 create mode 100644 man/man3/tomo-Num.j1.3 create mode 100644 man/man3/tomo-Num.log.3 create mode 100644 man/man3/tomo-Num.log10.3 create mode 100644 man/man3/tomo-Num.log1p.3 create mode 100644 man/man3/tomo-Num.log2.3 create mode 100644 man/man3/tomo-Num.logb.3 create mode 100644 man/man3/tomo-Num.mix.3 create mode 100644 man/man3/tomo-Num.near.3 create mode 100644 man/man3/tomo-Num.nextafter.3 create mode 100644 man/man3/tomo-Num.parse.3 create mode 100644 man/man3/tomo-Num.percent.3 create mode 100644 man/man3/tomo-Num.rint.3 create mode 100644 man/man3/tomo-Num.round.3 create mode 100644 man/man3/tomo-Num.scientific.3 create mode 100644 man/man3/tomo-Num.significand.3 create mode 100644 man/man3/tomo-Num.sin.3 create mode 100644 man/man3/tomo-Num.sinh.3 create mode 100644 man/man3/tomo-Num.sqrt.3 create mode 100644 man/man3/tomo-Num.tan.3 create mode 100644 man/man3/tomo-Num.tanh.3 create mode 100644 man/man3/tomo-Num.tgamma.3 create mode 100644 man/man3/tomo-Num.trunc.3 create mode 100644 man/man3/tomo-Num.y0.3 create mode 100644 man/man3/tomo-Num.y1.3 create mode 100644 man/man3/tomo-Path.accessed.3 create mode 100644 man/man3/tomo-Path.append.3 create mode 100644 man/man3/tomo-Path.append_bytes.3 create mode 100644 man/man3/tomo-Path.base_name.3 create mode 100644 man/man3/tomo-Path.by_line.3 create mode 100644 man/man3/tomo-Path.can_execute.3 create mode 100644 man/man3/tomo-Path.can_read.3 create mode 100644 man/man3/tomo-Path.can_write.3 create mode 100644 man/man3/tomo-Path.changed.3 create mode 100644 man/man3/tomo-Path.child.3 create mode 100644 man/man3/tomo-Path.children.3 create mode 100644 man/man3/tomo-Path.create_directory.3 create mode 100644 man/man3/tomo-Path.current_dir.3 create mode 100644 man/man3/tomo-Path.exists.3 create mode 100644 man/man3/tomo-Path.expand_home.3 create mode 100644 man/man3/tomo-Path.extension.3 create mode 100644 man/man3/tomo-Path.files.3 create mode 100644 man/man3/tomo-Path.from_components.3 create mode 100644 man/man3/tomo-Path.glob.3 create mode 100644 man/man3/tomo-Path.group.3 create mode 100644 man/man3/tomo-Path.is_directory.3 create mode 100644 man/man3/tomo-Path.is_file.3 create mode 100644 man/man3/tomo-Path.is_socket.3 create mode 100644 man/man3/tomo-Path.is_symlink.3 create mode 100644 man/man3/tomo-Path.modified.3 create mode 100644 man/man3/tomo-Path.owner.3 create mode 100644 man/man3/tomo-Path.parent.3 create mode 100644 man/man3/tomo-Path.read.3 create mode 100644 man/man3/tomo-Path.read_bytes.3 create mode 100644 man/man3/tomo-Path.relative_to.3 create mode 100644 man/man3/tomo-Path.remove.3 create mode 100644 man/man3/tomo-Path.resolved.3 create mode 100644 man/man3/tomo-Path.set_owner.3 create mode 100644 man/man3/tomo-Path.subdirectories.3 create mode 100644 man/man3/tomo-Path.unique_directory.3 create mode 100644 man/man3/tomo-Path.write.3 create mode 100644 man/man3/tomo-Path.write_bytes.3 create mode 100644 man/man3/tomo-Path.write_unique.3 create mode 100644 man/man3/tomo-Path.write_unique_bytes.3 create mode 100644 man/man3/tomo-Set.add.3 create mode 100644 man/man3/tomo-Set.add_all.3 create mode 100644 man/man3/tomo-Set.clear.3 create mode 100644 man/man3/tomo-Set.has.3 create mode 100644 man/man3/tomo-Set.is_subset_of.3 create mode 100644 man/man3/tomo-Set.is_superset_of.3 create mode 100644 man/man3/tomo-Set.overlap.3 create mode 100644 man/man3/tomo-Set.remove.3 create mode 100644 man/man3/tomo-Set.remove_all.3 create mode 100644 man/man3/tomo-Set.with.3 create mode 100644 man/man3/tomo-Set.without.3 create mode 100644 man/man3/tomo-Table.clear.3 create mode 100644 man/man3/tomo-Table.get.3 create mode 100644 man/man3/tomo-Table.get_or_set.3 create mode 100644 man/man3/tomo-Table.has.3 create mode 100644 man/man3/tomo-Table.remove.3 create mode 100644 man/man3/tomo-Table.set.3 create mode 100644 man/man3/tomo-Text.as_c_string.3 create mode 100644 man/man3/tomo-Text.at.3 create mode 100644 man/man3/tomo-Text.by_line.3 create mode 100644 man/man3/tomo-Text.by_split.3 create mode 100644 man/man3/tomo-Text.by_split_any.3 create mode 100644 man/man3/tomo-Text.bytes.3 create mode 100644 man/man3/tomo-Text.caseless_equals.3 create mode 100644 man/man3/tomo-Text.codepoint_names.3 create mode 100644 man/man3/tomo-Text.ends_with.3 create mode 100644 man/man3/tomo-Text.from.3 create mode 100644 man/man3/tomo-Text.from_bytes.3 create mode 100644 man/man3/tomo-Text.from_c_string.3 create mode 100644 man/man3/tomo-Text.from_codepoint_names.3 create mode 100644 man/man3/tomo-Text.from_codepoints.3 create mode 100644 man/man3/tomo-Text.has.3 create mode 100644 man/man3/tomo-Text.join.3 create mode 100644 man/man3/tomo-Text.left_pad.3 create mode 100644 man/man3/tomo-Text.lines.3 create mode 100644 man/man3/tomo-Text.lower.3 create mode 100644 man/man3/tomo-Text.middle_pad.3 create mode 100644 man/man3/tomo-Text.quoted.3 create mode 100644 man/man3/tomo-Text.repeat.3 create mode 100644 man/man3/tomo-Text.replace.3 create mode 100644 man/man3/tomo-Text.reversed.3 create mode 100644 man/man3/tomo-Text.right_pad.3 create mode 100644 man/man3/tomo-Text.slice.3 create mode 100644 man/man3/tomo-Text.split.3 create mode 100644 man/man3/tomo-Text.split_any.3 create mode 100644 man/man3/tomo-Text.starts_with.3 create mode 100644 man/man3/tomo-Text.title.3 create mode 100644 man/man3/tomo-Text.to.3 create mode 100644 man/man3/tomo-Text.translate.3 create mode 100644 man/man3/tomo-Text.trim.3 create mode 100644 man/man3/tomo-Text.upper.3 create mode 100644 man/man3/tomo-Text.utf32_codepoints.3 create mode 100644 man/man3/tomo-Text.width.3 create mode 100644 man/man3/tomo-Text.without_prefix.3 create mode 100644 man/man3/tomo-Text.without_suffix.3 create mode 100644 man/man3/tomo-USE_COLOR.3 create mode 100644 man/man3/tomo-ask.3 create mode 100644 man/man3/tomo-exit.3 create mode 100644 man/man3/tomo-fail.3 create mode 100644 man/man3/tomo-getenv.3 create mode 100644 man/man3/tomo-print.3 create mode 100644 man/man3/tomo-say.3 create mode 100644 man/man3/tomo-setenv.3 create mode 100644 man/man3/tomo-sleep.3 create mode 100755 scripts/api_gen.py diff --git a/Makefile b/Makefile index 44179f7e..9d3da806 100644 --- a/Makefile +++ b/Makefile @@ -74,6 +74,8 @@ endif COMPILER_OBJS=$(patsubst %.c,%.o,$(wildcard src/*.c)) STDLIB_OBJS=$(patsubst %.c,%.o,$(wildcard src/stdlib/*.c)) TESTS=$(patsubst test/%.tm,test/results/%.tm.testresult,$(wildcard test/*.tm)) +API_YAML=$(wildcard api/*.yaml) +API_MD=$(patsubst %.yaml,%.md,$(API_YAML)) all: config.mk build/lib/$(LIB_FILE) build/lib/$(AR_FILE) build/bin/tomo @@ -123,6 +125,19 @@ clean: %: %.md pandoc --lua-filter=docs/.pandoc/bold-code.lua -s $< -t man -o $@ +%.md: %.yaml scripts/api_gen.py + ./scripts/api_gen.py $< >$@ + +api/api.md: $(API_YAML) + ./scripts/api_gen.py $^ >$@ + +.PHONY: api-docs +api-docs: $(API_MD) api/api.md + +.PHONY: manpages +manpages: $(API_YAML) + ./scripts/mandoc_gen.py $^ + examples: ./build/bin/tomo -qIL examples/log examples/ini examples/vectors examples/http examples/wrap examples/colorful ./build/bin/tomo -e examples/game/game.tm examples/http-server/http-server.tm \ @@ -156,7 +171,8 @@ install-files: build/bin/tomo build/lib/$(LIB_FILE) build/lib/$(AR_FILE) cp -v build/lib/$(LIB_FILE) build/lib/$(AR_FILE) "$(PREFIX)/lib/" rm -f "$(PREFIX)/bin/tomo" cp -v build/bin/tomo "$(PREFIX)/bin/" - cp -v docs/tomo.1 "$(PREFIX)/man/man1/" + cp -v man/man1/* "$(PREFIX)/man/man1/" + cp -v man/man3/* "$(PREFIX)/man/man3/" install-libs: build/bin/tomo ./local-tomo -qIL lib/patterns lib/time lib/commands lib/shell lib/random lib/base64 lib/pthreads lib/uuid lib/core diff --git a/api/api.md b/api/api.md new file mode 100644 index 00000000..b98757b2 --- /dev/null +++ b/api/api.md @@ -0,0 +1,4814 @@ +% API + +# Builtins +## USE_COLOR + +```tomo +USE_COLOR : Bool +``` + +Whether or not the console prefers ANSI color escape sequences in the output. + +## ask + +```tomo +ask : func(prompt: Text, bold: Bool = yes, force_tty: Bool = yes -> Text?) +``` + +Gets a line of user input text with a prompt. + +When a program is receiving input from a pipe or writing its output to a pipe, this flag (which is enabled by default) forces the program to write the prompt to `/dev/tty` and read the input from `/dev/tty`, which circumvents the pipe. This means that `foo | ./tomo your-program | baz` will still show a visible prompt and read user input, despite the pipes. Setting this flag to `no` will mean that the prompt is written to `stdout` and input is read from `stdin`, even if those are pipes. + +Argument | Type | Description | Default +---------|------|-------------|--------- +prompt | `Text` | The text to print as a prompt before getting the input. | +bold | `Bool` | Whether or not to print make the prompt appear bold on a console. | **Default:** `yes` +force_tty | `Bool` | Whether or not to force the use of /dev/tty. | **Default:** `yes` + +**Return:** A line of user input text without a trailing newline, or empty text if something went wrong (e.g. the user hit `Ctrl-D`). + + +**Example:** +```tomo +>> ask("What's your name? ") += "Arthur Dent" + +``` +## exit + +```tomo +exit : func(message: Text? = !Text, status: Int32 = Int32(1) -> Void) +``` + +Exits the program with a given status and optionally prints a message. + +Argument | Type | Description | Default +---------|------|-------------|--------- +message | `Text?` | If nonempty, this message will be printed (with a newline) before exiting. | **Default:** `!Text` +status | `Int32` | The status code that the program with exit with. | **Default:** `Int32(1)` + +**Return:** This function never returns. + + +**Example:** +```tomo +exit(status=1, "Goodbye forever!") + +``` +## fail + +```tomo +fail : func(message: Text -> Abort) +``` + +Prints a message to the console, aborts the program, and prints a stack trace. + +Argument | Type | Description | Default +---------|------|-------------|--------- +message | `Text` | The error message to print. | + +**Return:** Nothing, aborts the program. + + +**Example:** +```tomo +fail("Oh no!") + +``` +## getenv + +```tomo +getenv : func(name: Text -> Text?) +``` + +Gets an environment variable. + +Argument | Type | Description | Default +---------|------|-------------|--------- +name | `Text` | The name of the environment variable to get. | + +**Return:** If set, the environment variable's value, otherwise, `none`. + + +**Example:** +```tomo +>> getenv("TERM") += "xterm-256color"? + +``` +## print + +```tomo +print : func(text: Text, newline: Bool = yes -> Void) +``` + +Prints a message to the console (alias for [`say`](#say)). + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to print. | +newline | `Bool` | Whether or not to print a newline after the text. | **Default:** `yes` + +**Return:** Nothing. + + +**Example:** +```tomo +print("Hello ", newline=no) +print("world!") + +``` +## say + +```tomo +say : func(text: Text, newline: Bool = yes -> Void) +``` + +Prints a message to the console. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to print. | +newline | `Bool` | Whether or not to print a newline after the text. | **Default:** `yes` + +**Return:** Nothing. + + +**Example:** +```tomo +say("Hello ", newline=no) +say("world!") + +``` +## setenv + +```tomo +setenv : func(name: Text, value: Text -> Void) +``` + +Sets an environment variable. + +Argument | Type | Description | Default +---------|------|-------------|--------- +name | `Text` | The name of the environment variable to set. | +value | `Text` | The new value of the environment variable. | + +**Return:** Nothing. + + +**Example:** +```tomo +setenv("FOOBAR", "xyz") + +``` +## sleep + +```tomo +sleep : func(seconds: Num -> Void) +``` + +Pause execution for a given number of seconds. + +Argument | Type | Description | Default +---------|------|-------------|--------- +seconds | `Num` | How many seconds to sleep for. | + +**Return:** Nothing. + + +**Example:** +```tomo +sleep(1.5) + +``` + +# Bool +## Bool.parse + +```tomo +Bool.parse : func(text: Text -> Bool?) +``` + +Converts a string representation of a boolean value into a boolean. Acceptable boolean values are case-insensitive variations of `yes`/`no`, `y`/`n`, `true`/`false`, `on`/`off`. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The string containing the boolean value. | + +**Return:** `yes` if the string matches a recognized truthy boolean value; otherwise return `no`. + + +**Example:** +```tomo +>> Bool.parse("yes") += yes : Bool? +>> Bool.parse("no") += no : Bool? +>> Bool.parse("???") += none : Bool? + +``` + +# Byte +## Byte.hex + +```tomo +Byte.hex : func(byte: Byte, uppercase: Bool = yes, prefix: Bool = no -> Text) +``` + +Convert a byte to a hexidecimal text representation. + +Argument | Type | Description | Default +---------|------|-------------|--------- +byte | `Byte` | The byte to convert to hex. | +uppercase | `Bool` | Whether or not to use uppercase hexidecimal letters. | **Default:** `yes` +prefix | `Bool` | Whether or not to prepend a `0x` prefix. | **Default:** `no` + +**Return:** The byte as a hexidecimal text. + + +**Example:** +```tomo +>> Byte(18).hex() += "0x12" + +``` +## Byte.is_between + +```tomo +Byte.is_between : func(x: Byte, low: Byte, high: Byte -> Bool) +``` + +Determines if an integer is between two numbers (inclusive). + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Byte` | The integer to be checked. | +low | `Byte` | The lower bound to check (inclusive). | +high | `Byte` | The upper bound to check (inclusive). | + +**Return:** `yes` if `low <= x and x <= high`, otherwise `no` + + +**Example:** +```tomo +>> Byte(7).is_between(1, 10) += yes +>> Byte(7).is_between(100, 200) += no +>> Byte(7).is_between(1, 7) += yes + +``` +## Byte.parse + +```tomo +Byte.parse : func(text: Text -> Byte?) +``` + +Parse a byte literal from text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to parse. | + +**Return:** The byte parsed from the text, if successful, otherwise `none`. + + +**Example:** +```tomo +>> Byte.parse("5") += Byte(5)? +>> Byte.parse("asdf") += none + +``` +## Byte.to + +```tomo +Byte.to : func(first: Byte, last: Byte, step: Byte? = none -> func(->Byte?)) +``` + +Returns an iterator function that iterates over the range of bytes specified. + +Argument | Type | Description | Default +---------|------|-------------|--------- +first | `Byte` | The starting value of the range. | +last | `Byte` | The ending value of the range. | +step | `Byte?` | An optional step size to use. If unspecified or `none`, the step will be inferred to be `+1` if `last >= first`, otherwise `-1`. | **Default:** `none` + +**Return:** An iterator function that returns each byte in the given range (inclusive). + + +**Example:** +```tomo +>> Byte(2).to(5) += func(->Byte?) +>> [x for x in Byte(2).to(5)] += [Byte(2), Byte(3), Byte(4), Byte(5)] +>> [x for x in Byte(5).to(2)] += [Byte(5), Byte(4), Byte(3), Byte(2)] + +>> [x for x in Byte(2).to(5, step=2)] += [Byte(2), Byte(4)] + +``` + +# Int +## Int.abs + +```tomo +Int.abs : func(x: Int -> Int) +``` + +Calculates the absolute value of an integer. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Int` | The integer whose absolute value is to be calculated. | + +**Return:** The absolute value of `x`. + + +**Example:** +```tomo +>> (-10).abs() += 10 + +``` +## Int.choose + +```tomo +Int.choose : func(n: Int, k: Int -> Int) +``` + +Computes the binomial coefficient of the given numbers (the equivalent of `n` choose `k` in combinatorics). This is equal to `n.factorial()/(k.factorial() * (n-k).factorial())`. + +Argument | Type | Description | Default +---------|------|-------------|--------- +n | `Int` | The number of things to choose from. | +k | `Int` | The number of things to be chosen. | + +**Return:** The binomial coefficient, equivalent to the number of ways to uniquely choose `k` objects from among `n` objects, ignoring order. + + +**Example:** +```tomo +>> (4).choose(2) += 6 + +``` +## Int.clamped + +```tomo +Int.clamped : func(x: Int, low: Int, high: Int -> Int) +``` + +Returns the given number clamped between two values so that it is within that range. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Int` | The integer to clamp. | +low | `Int` | The lowest value the result can take. | +high | `Int` | The highest value the result can take. | + +**Return:** The first argument clamped between the other two arguments. + + +**Example:** +```tomo +>> (2).clamped(5, 10) += 5 + +``` +## Int.factorial + +```tomo +Int.factorial : func(n: Int -> Text) +``` + +Computes the factorial of an integer. + +Argument | Type | Description | Default +---------|------|-------------|--------- +n | `Int` | The integer to compute the factorial of. | + +**Return:** The factorial of the given integer. + + +**Example:** +```tomo +>> (10).factorial() += 3628800 + +``` +## Int.format + +```tomo +Int.format : func(i: Int, digits: Int = 0 -> Text) +``` + +Formats an integer as a string with a specified number of digits. + +Argument | Type | Description | Default +---------|------|-------------|--------- +i | `Int` | The integer to be formatted. | +digits | `Int` | The minimum number of digits to which the integer should be padded. | **Default:** `0` + +**Return:** A string representation of the integer, padded to the specified number of digits. + + +**Example:** +```tomo +>> (42).format(digits=5) += "00042" + +``` +## Int.hex + +```tomo +Int.hex : func(i: Int, digits: Int = 0, uppercase: Bool = yes, prefix: Bool = yes -> Text) +``` + +Converts an integer to its hexadecimal representation. + +Argument | Type | Description | Default +---------|------|-------------|--------- +i | `Int` | The integer to be converted. | +digits | `Int` | The minimum number of digits in the output string. | **Default:** `0` +uppercase | `Bool` | Whether to use uppercase letters for hexadecimal digits. | **Default:** `yes` +prefix | `Bool` | Whether to include a "0x" prefix. | **Default:** `yes` + +**Return:** The hexadecimal string representation of the integer. + + +**Example:** +```tomo +>> (255).hex(digits=4, uppercase=yes, prefix=yes) += "0x00FF" + +``` +## Int.is_between + +```tomo +Int.is_between : func(x: Int, low: Int, high: Int -> Bool) +``` + +Determines if an integer is between two numbers (inclusive). + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Int` | The integer to be checked. | +low | `Int` | The lower bound to check (inclusive). | +high | `Int` | The upper bound to check (inclusive). | + +**Return:** `yes` if `low <= x and x <= high`, otherwise `no` + + +**Example:** +```tomo +>> (7).is_between(1, 10) += yes +>> (7).is_between(100, 200) += no +>> (7).is_between(1, 7) += yes + +``` +## Int.is_prime + +```tomo +Int.is_prime : func(x: Int, reps: Int = 50 -> Bool) +``` + +Determines if an integer is a prime number. + +This function is _probabilistic_. With the default arguments, the chances of getting an incorrect answer are astronomically small (on the order of 10^(-30)). See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp) for more details. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Int` | The integer to be checked. | +reps | `Int` | The number of repetitions for primality tests. | **Default:** `50` + +**Return:** `yes` if `x` is a prime number, `no` otherwise. + + +**Example:** +```tomo +>> (7).is_prime() += yes +>> (6).is_prime() += no + +``` +## Int.next_prime + +```tomo +Int.next_prime : func(x: Int -> Int) +``` + +Finds the next prime number greater than the given integer. + +This function is _probabilistic_, but the chances of getting an incorrect answer are astronomically small (on the order of 10^(-30)). See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp) for more details. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Int` | The integer after which to find the next prime. | + +**Return:** The next prime number greater than `x`. + + +**Example:** +```tomo +>> (11).next_prime() += 13 + +``` +## Int.octal + +```tomo +Int.octal : func(i: Int, digits: Int = 0, prefix: Bool = yes -> Text) +``` + +Converts an integer to its octal representation. + +Argument | Type | Description | Default +---------|------|-------------|--------- +i | `Int` | The integer to be converted. | +digits | `Int` | The minimum number of digits in the output string. | **Default:** `0` +prefix | `Bool` | Whether to include a "0o" prefix. | **Default:** `yes` + +**Return:** The octal string representation of the integer. + + +**Example:** +```tomo +>> (64).octal(digits=4, prefix=yes) += "0o0100" + +``` +## Int.onward + +```tomo +Int.onward : func(first: Int, step: Int = 1 -> Text) +``` + +Return an iterator that counts infinitely from the starting integer (with an optional step size). + +Argument | Type | Description | Default +---------|------|-------------|--------- +first | `Int` | The starting integer. | +step | `Int` | The increment step size. | **Default:** `1` + +**Return:** An iterator function that counts onward from the starting integer. + + +**Example:** +```tomo +nums : &[Int] = &[] +for i in (5).onward() +nums.insert(i) +stop if i == 10 +>> nums[] += [5, 6, 7, 8, 9, 10] + +``` +## Int.parse + +```tomo +Int.parse : func(text: Text -> Int?) +``` + +Converts a text representation of an integer into an integer. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text containing the integer. | + +**Return:** The integer represented by the text. If the given text contains a value outside of the representable range or if the entire text can't be parsed as an integer, `none` will be returned. + + +**Example:** +```tomo +>> Int.parse("123") += 123 : Int? +>> Int.parse("0xFF") += 255 : Int? + +# Can't parse: +>> Int.parse("asdf") += none : Int? + +# Outside valid range: +>> Int8.parse("9999999") += none : Int8? + +``` +## Int.prev_prime + +```tomo +Int.prev_prime : func(x: Int -> Int?) +``` + +Finds the previous prime number less than the given integer. If there is no previous prime number (i.e. if a number less than `2` is provided), then the function will create a runtime error. + +This function is _probabilistic_, but the chances of getting an incorrect answer are astronomically small (on the order of 10^(-30)). See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp) for more details. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Int` | The integer before which to find the previous prime. | + +**Return:** The previous prime number less than `x`, or `none` if `x` is less than 2. + + +**Example:** +```tomo +>> (11).prev_prime() += 7 + +``` +## Int.sqrt + +```tomo +Int.sqrt : func(x: Int -> Int) +``` + +Calculates the nearest square root of an integer. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Int` | The integer whose square root is to be calculated. | + +**Return:** The integer part of the square root of `x`. + + +**Example:** +```tomo +>> (16).sqrt() += 4 +>> (17).sqrt() += 4 + +``` +## Int.to + +```tomo +Int.to : func(first: Int, last: Int, step: Int? = none -> func(->Int?)) +``` + +Returns an iterator function that iterates over the range of numbers specified. + +Argument | Type | Description | Default +---------|------|-------------|--------- +first | `Int` | The starting value of the range. | +last | `Int` | The ending value of the range. | +step | `Int?` | An optional step size to use. If unspecified or `none`, the step will be inferred to be `+1` if `last >= first`, otherwise `-1`. | **Default:** `none` + +**Return:** An iterator function that returns each integer in the given range (inclusive). + + +**Example:** +```tomo +>> (2).to(5) += func(->Int?) +>> [x for x in (2).to(5)] += [2, 3, 4, 5] +>> [x for x in (5).to(2)] += [5, 4, 3, 2] + +>> [x for x in (2).to(5, step=2)] += [2, 4] + +``` + +# List +## List.binary_search + +```tomo +List.binary_search : func(list: [T], by: func(x,y:&T->Int32) = T.compare -> Int) +``` + +Performs a binary search on a sorted list. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The sorted list to search. | +by | `func(x,y:&T->Int32)` | The comparison function used to determine order. If not specified, the default comparison function for the item type will be used. | **Default:** `T.compare` + +**Return:** Assuming the input list is sorted according to the given comparison function, return the index where the given item would be inserted to maintain the sorted order. That is, if the item is found, return its index, otherwise return the place where it would be found if it were inserted and the list were sorted. + + +**Example:** +```tomo +>> [1, 3, 5, 7, 9].binary_search(5) += 3 + +>> [1, 3, 5, 7, 9].binary_search(-999) += 1 + +>> [1, 3, 5, 7, 9].binary_search(999) += 6 + +``` +## List.by + +```tomo +List.by : func(list: [T], step: Int -> [T]) +``` + +Creates a new list with elements spaced by the specified step value. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The original list. | +step | `Int` | The step value for selecting elements. | + +**Return:** A new list with every `step`-th element from the original list. + + +**Example:** +```tomo +>> [1, 2, 3, 4, 5, 6].by(2) += [1, 3, 5] + +``` +## List.clear + +```tomo +List.clear : func(list: @[T] -> Void) +``` + +Clears all elements from the list. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `@[T]` | The mutable reference to the list to be cleared. | + +**Return:** Nothing. + + +**Example:** +```tomo +>> my_list.clear() + +``` +## List.counts + +```tomo +List.counts : func(list: [T] -> {T=Int}) +``` + +Counts the occurrences of each element in the list. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The list to count elements in. | + +**Return:** A table mapping each element to its count. + + +**Example:** +```tomo +>> [10, 20, 30, 30, 30].counts() += {10=1, 20=1, 30=3} + +``` +## List.find + +```tomo +List.find : func(list: [T], target: T -> Int?) +``` + +Finds the index of the first occurrence of an element (if any). + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The list to search through. | +target | `T` | The item to search for. | + +**Return:** The index of the first occurrence or `!Int` if not found. + + +**Example:** +```tomo +>> [10, 20, 30, 40, 50].find(20) += 2 : Int? + +>> [10, 20, 30, 40, 50].find(9999) += none : Int? + +``` +## List.first + +```tomo +List.first : func(list: [T], predicate: func(item:&T -> Bool) -> Int) +``` + +Find the index of the first item that matches a predicate function (if any). + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The list to search through. | +predicate | `func(item:&T -> Bool)` | A function that returns `yes` if the item should be returned or `no` if it should not. | + +**Return:** Returns the index of the first item where the predicate is true or `!Int` if no item matches. + + +**Example:** +```tomo +>> [4, 5, 6].find(func(i:&Int): i.is_prime()) += 5 : Int? +>> [4, 6, 8].find(func(i:&Int): i.is_prime()) += none : Int? + +``` +## List.from + +```tomo +List.from : func(list: [T], first: Int -> [T]) +``` + +Returns a slice of the list starting from a specified index. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The original list. | +first | `Int` | The index to start from. | + +**Return:** A new list starting from the specified index. + + +**Example:** +```tomo +>> [10, 20, 30, 40, 50].from(3) += [30, 40, 50] + +``` +## List.has + +```tomo +List.has : func(list: [T], target: T -> Bool) +``` + +Checks if the list has an element. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The list to check. | +target | `T` | The element to check for. | + +**Return:** `yes` if the list has the element, `no` otherwise. + + +**Example:** +```tomo +>> [10, 20, 30].has(20) += yes + +``` +## List.heap_pop + +```tomo +List.heap_pop : func(list: @[T], by: func(x,y:&T->Int32) = T.compare -> T?) +``` + +Removes and returns the top element of a heap or `none` if the list is empty. By default, this is the *minimum* value in the heap. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `@[T]` | The mutable reference to the heap. | +by | `func(x,y:&T->Int32)` | The comparison function used to determine order. If not specified, the default comparison function for the item type will be used. | **Default:** `T.compare` + +**Return:** The removed top element of the heap or `none` if the list is empty. + + +**Example:** +```tomo +>> my_heap := [30, 10, 20] +>> my_heap.heapify() +>> my_heap.heap_pop() += 10 + +``` +## List.heap_push + +```tomo +List.heap_push : func(list: @[T], item: T, by = T.compare -> Void) +``` + +Adds an element to the heap and maintains the heap property. By default, this is a *minimum* heap. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `@[T]` | The mutable reference to the heap. | +item | `T` | The item to be added. | +by | `` | The comparison function used to determine order. If not specified, the default comparison function for the item type will be used. | **Default:** `T.compare` + +**Return:** Nothing. + + +**Example:** +```tomo +>> my_heap.heap_push(10) + +``` +## List.heapify + +```tomo +List.heapify : func(list: @[T], by: func(x,y:&T->Int32) = T.compare -> Void) +``` + +Converts a list into a heap. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `@[T]` | The mutable reference to the list to be heapified. | +by | `func(x,y:&T->Int32)` | The comparison function used to determine order. If not specified, the default comparison function for the item type will be used. | **Default:** `T.compare` + +**Return:** Nothing. + + +**Example:** +```tomo +>> my_heap := [30, 10, 20] +>> my_heap.heapify() + +``` +## List.insert + +```tomo +List.insert : func(list: @[T], item: T, at: Int = 0 -> Void) +``` + +Inserts an element at a specified position in the list. + +Since indices are 1-indexed and negative indices mean "starting from the back", an index of `0` means "after the last item". + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `@[T]` | The mutable reference to the list. | +item | `T` | The item to be inserted. | +at | `Int` | The index at which to insert the item. | **Default:** `0` + +**Return:** Nothing. + + +**Example:** +```tomo +>> list := [10, 20] +>> list.insert(30) +>> list += [10, 20, 30] + +>> list.insert(999, at=2) +>> list += [10, 999, 20, 30] + +``` +## List.insert_all + +```tomo +List.insert_all : func(list: @[T], items: [T], at: Int = 0 -> Void) +``` + +Inserts a list of items at a specified position in the list. + +Since indices are 1-indexed and negative indices mean "starting from the back", an index of `0` means "after the last item". + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `@[T]` | The mutable reference to the list. | +items | `[T]` | The items to be inserted. | +at | `Int` | The index at which to insert the item. | **Default:** `0` + +**Return:** Nothing. + + +**Example:** +```tomo +list := [10, 20] +list.insert_all([30, 40]) +>> list += [10, 20, 30, 40] + +list.insert_all([99, 100], at=2) +>> list += [10, 99, 100, 20, 30, 40] + +``` +## List.pop + +```tomo +List.pop : func(list: &[T], index: Int = -1 -> T?) +``` + +Removes and returns an item from the list. If the given index is present in the list, the item at that index will be removed and the list will become one element shorter. + +Since negative indices are counted from the back, the default behavior is to pop the last value. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `&[T]` | The list to remove an item from. | +index | `Int` | The index from which to remove the item. | **Default:** `-1` + +**Return:** `none` if the list is empty or the given index does not exist in the list, otherwise the item at the given index. + + +**Example:** +```tomo +>> list := [10, 20, 30, 40] + +>> list.pop() += 40 +>> list += &[10, 20, 30] + +>> list.pop(index=2) += 20 +>> list += &[10, 30] + +``` +## List.random + +```tomo +List.random : func(list: [T], random: func(min,max:Int64->Int64)? = none -> T) +``` + +Selects a random element from the list. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The list from which to select a random element. | +random | `func(min,max:Int64->Int64)?` | If provided, this function will be used to get a random index in the list. Returned values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number generation) | **Default:** `none` + +**Return:** A random element from the list. + + +**Example:** +```tomo +>> [10, 20, 30].random() += 20 + +``` +## List.remove_at + +```tomo +List.remove_at : func(list: @[T], at: Int = -1, count: Int = 1 -> Void) +``` + +Removes elements from the list starting at a specified index. + +Since negative indices are counted from the back, the default behavior is to remove the last item. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `@[T]` | The mutable reference to the list. | +at | `Int` | The index at which to start removing elements. | **Default:** `-1` +count | `Int` | The number of elements to remove. | **Default:** `1` + +**Return:** Nothing. + + +**Example:** +```tomo +list := [10, 20, 30, 40, 50] +list.remove_at(2) +>> list += [10, 30, 40, 50] + +list.remove_at(2, count=2) +>> list += [10, 50] + +``` +## List.remove_item + +```tomo +List.remove_item : func(list: @[T], item: T, max_count: Int = -1 -> Void) +``` + +Removes all occurrences of a specified item from the list. + +A negative `max_count` means "remove all occurrences". + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `@[T]` | The mutable reference to the list. | +item | `T` | The item to be removed. | +max_count | `Int` | The maximum number of occurrences to remove. | **Default:** `-1` + +**Return:** Nothing. + + +**Example:** +```tomo +list := [10, 20, 10, 20, 30] +list.remove_item(10) +>> list += [20, 20, 30] + +list.remove_item(20, max_count=1) +>> list += [20, 30] + +``` +## List.reversed + +```tomo +List.reversed : func(list: [T] -> [T]) +``` + +Returns a reversed slice of the list. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The list to be reversed. | + +**Return:** A slice of the list with elements in reverse order. + + +**Example:** +```tomo +>> [10, 20, 30].reversed() += [30, 20, 10] + +``` +## List.sample + +```tomo +List.sample : func(list: [T], count: Int, weights: [Num]? = ![Num], random: func(->Num)? = none -> [T]) +``` + +Selects a sample of elements from the list, optionally with weighted probabilities. + +Errors will be raised if any of the following conditions occurs: - The given list has no elements and `count >= 1` - `count < 0` (negative count) - The number of weights provided doesn't match the length of the list. - Any weight in the weights list is negative, infinite, or `NaN` - The sum of the given weights is zero (zero probability for every element). + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The list to sample from. | +count | `Int` | The number of elements to sample. | +weights | `[Num]?` | The probability weights for each element in the list. These values do not need to add up to any particular number, they are relative weights. If no weights are given, elements will be sampled with uniform probability. | **Default:** `![Num]` +random | `func(->Num)?` | If provided, this function will be used to get random values for sampling the list. The provided function should return random numbers between `0.0` (inclusive) and `1.0` (exclusive). (Used for deterministic pseudorandom number generation) | **Default:** `none` + +**Return:** A list of sampled elements from the list. + + +**Example:** +```tomo +>> [10, 20, 30].sample(2, weights=[90%, 5%, 5%]) += [10, 10] + +``` +## List.shuffle + +```tomo +List.shuffle : func(list: @[T], random: func(min,max:Int64->Int64)? = none -> Void) +``` + +Shuffles the elements of the list in place. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `@[T]` | The mutable reference to the list to be shuffled. | +random | `func(min,max:Int64->Int64)?` | If provided, this function will be used to get a random index in the list. Returned values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number generation) | **Default:** `none` + +**Return:** Nothing. + + +**Example:** +```tomo +>> list.shuffle() + +``` +## List.shuffled + +```tomo +List.shuffled : func(list: [T], random: func(min,max:Int64->Int64)? = none -> [T]) +``` + +Creates a new list with elements shuffled. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The list to be shuffled. | +random | `func(min,max:Int64->Int64)?` | If provided, this function will be used to get a random index in the list. Returned values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number generation) | **Default:** `none` + +**Return:** A new list with shuffled elements. + + +**Example:** +```tomo +>> [10, 20, 30, 40].shuffled() += [40, 10, 30, 20] + +``` +## List.slice + +```tomo +List.slice : func(list: [T], from: Int, to: Int -> [T]) +``` + +Returns a slice of the list spanning the given indices (inclusive). + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The original list. | +from | `Int` | The first index to include. | +to | `Int` | The last index to include. | + +**Return:** A new list spanning the given indices. Note: negative indices are counted from the back of the list, so `-1` refers to the last element, `-2` the second-to-last, and so on. + + +**Example:** +```tomo +>> [10, 20, 30, 40, 50].slice(2, 4) += [20, 30, 40] + +>> [10, 20, 30, 40, 50].slice(-3, -2) += [30, 40] + +``` +## List.sort + +```tomo +List.sort : func(list: @[T], by = T.compare -> Void) +``` + +Sorts the elements of the list in place in ascending order (small to large). + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `@[T]` | The mutable reference to the list to be sorted. | +by | `` | The comparison function used to determine order. If not specified, the default comparison function for the item type will be used. | **Default:** `T.compare` + +**Return:** Nothing. + + +**Example:** +```tomo +list := [40, 10, -30, 20] +list.sort() +>> list += [-30, 10, 20, 40] + +list.sort(func(a,b:&Int): a.abs() <> b.abs()) +>> list += [10, 20, -30, 40] + +``` +## List.sorted + +```tomo +List.sorted : func(list: [T], by = T.compare -> [T]) +``` + +Creates a new list with elements sorted. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The list to be sorted. | +by | `` | The comparison function used to determine order. If not specified, the default comparison function for the item type will be used. | **Default:** `T.compare` + +**Return:** A new list with sorted elements. + + +**Example:** +```tomo +>> [40, 10, -30, 20].sorted() += [-30, 10, 20, 40] + +>> [40, 10, -30, 20].sorted(func(a,b:&Int): a.abs() <> b.abs()) += [10, 20, -30, 40] + +``` +## List.to + +```tomo +List.to : func(list: [T], last: Int -> [T]) +``` + +Returns a slice of the list from the start of the original list up to a specified index (inclusive). + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The original list. | +last | `Int` | The index up to which elements should be included. | + +**Return:** A new list containing elements from the start up to the specified index. + + +**Example:** +```tomo +>> [10, 20, 30, 40, 50].to(3) += [10, 20, 30] + +>> [10, 20, 30, 40, 50].to(-2) += [10, 20, 30, 40] + +``` +## List.unique + +```tomo +List.unique : func(list: [T] -> |T|) +``` + +Returns a Set that contains the unique elements of the list. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The list to process. | + +**Return:** A set containing only unique elements from the list. + + +**Example:** +```tomo +>> [10, 20, 10, 10, 30].unique() += {10, 20, 30} + +``` + +# Num +## Num.1_PI + +```tomo +Num.1_PI : Num +``` + +The constant $\frac{1}{\pi}$. + +## Num.2_PI + +```tomo +Num.2_PI : Num +``` + +The constant $2 \times \pi$. + +## Num.2_SQRTPI + +```tomo +Num.2_SQRTPI : Num +``` + +The constant $2 \times \sqrt{\pi}$. + +## Num.E + +```tomo +Num.E : Num +``` + +The base of the natural logarithm ($e$). + +## Num.INF + +```tomo +Num.INF : Num +``` + +Positive infinity. + +## Num.LN10 + +```tomo +Num.LN10 : Num +``` + +The natural logarithm of 10. + +## Num.LN2 + +```tomo +Num.LN2 : Num +``` + +The natural logarithm of 2. + +## Num.LOG2E + +```tomo +Num.LOG2E : Num +``` + +The base 2 logarithm of $e$ + +## Num.PI + +```tomo +Num.PI : Num +``` + +Pi ($\pi$). + +## Num.PI_2 + +```tomo +Num.PI_2 : Num +``` + +$\frac{\pi}{2}$ + +## Num.PI_4 + +```tomo +Num.PI_4 : Num +``` + +$\frac{\pi}{4}$ + +## Num.SQRT1_2 + +```tomo +Num.SQRT1_2 : Num +``` + +$\sqrt{\frac{1}{2}}$ + +## Num.SQRT2 + +```tomo +Num.SQRT2 : Num +``` + +$\sqrt{2}$ + +## Num.TAU + +```tomo +Num.TAU : Num +``` + +Tau ($2 \times \pi$) + +## Num.abs + +```tomo +Num.abs : func(n: Num -> Num) +``` + +Calculates the absolute value of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +n | `Num` | The number whose absolute value is to be computed. | + +**Return:** The absolute value of `n`. + + +**Example:** +```tomo +>> (-3.5).abs() += 3.5 + +``` +## Num.acos + +```tomo +Num.acos : func(x: Num -> Num) +``` + +Computes the arc cosine of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the arc cosine is to be calculated. | + +**Return:** The arc cosine of `x` in radians. + + +**Example:** +```tomo +>> (0.0).acos() // -> (π/2) += 1.5708 + +``` +## Num.acosh + +```tomo +Num.acosh : func(x: Num -> Num) +``` + +Computes the inverse hyperbolic cosine of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the inverse hyperbolic cosine is to be calculated. | + +**Return:** The inverse hyperbolic cosine of `x`. + + +**Example:** +```tomo +>> (1.0).acosh() += 0 + +``` +## Num.asin + +```tomo +Num.asin : func(x: Num -> Num) +``` + +Computes the arc sine of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the arc sine is to be calculated. | + +**Return:** The arc sine of `x` in radians. + + +**Example:** +```tomo +>> (0.5).asin() // -> (π/6) += 0.5236 + +``` +## Num.asinh + +```tomo +Num.asinh : func(x: Num -> Num) +``` + +Computes the inverse hyperbolic sine of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the inverse hyperbolic sine is to be calculated. | + +**Return:** The inverse hyperbolic sine of `x`. + + +**Example:** +```tomo +>> (0.0).asinh() += 0 + +``` +## Num.atan + +```tomo +Num.atan : func(x: Num -> Num) +``` + +Computes the arc tangent of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the arc tangent is to be calculated. | + +**Return:** The arc tangent of `x` in radians. + + +**Example:** +```tomo +>> (1.0).atan() // -> (π/4) += 0.7854 + +``` +## Num.atan2 + +```tomo +Num.atan2 : func(x: Num, y: Num -> Num) +``` + +Computes the arc tangent of the quotient of two numbers. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The numerator. | +y | `Num` | The denominator. | + +**Return:** The arc tangent of `x/y` in radians. + + +**Example:** +```tomo +>> Num.atan2(1, 1) // -> (π/4) += 0.7854 + +``` +## Num.atanh + +```tomo +Num.atanh : func(x: Num -> Num) +``` + +Computes the inverse hyperbolic tangent of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the inverse hyperbolic tangent is to be calculated. | + +**Return:** The inverse hyperbolic tangent of `x`. + + +**Example:** +```tomo +>> (0.5).atanh() += 0.5493 + +``` +## Num.cbrt + +```tomo +Num.cbrt : func(x: Num -> Num) +``` + +Computes the cube root of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the cube root is to be calculated. | + +**Return:** The cube root of `x`. + + +**Example:** +```tomo +>> (27.0).cbrt() += 3 + +``` +## Num.ceil + +```tomo +Num.ceil : func(x: Num -> Num) +``` + +Rounds a number up to the nearest integer. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number to be rounded up. | + +**Return:** The smallest integer greater than or equal to `x`. + + +**Example:** +```tomo +>> (3.2).ceil() += 4 + +``` +## Num.clamped + +```tomo +Num.clamped : func(x: Num, low: Num, high: Num -> Num) +``` + +Returns the given number clamped between two values so that it is within that range. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number to clamp. | +low | `Num` | The lowest value the result can take. | +high | `Num` | The highest value the result can take. | + +**Return:** The first argument clamped between the other two arguments. + + +**Example:** +```tomo +>> (2.5).clamped(5.5, 10.5) += 5.5 + +``` +## Num.copysign + +```tomo +Num.copysign : func(x: Num, y: Num -> Num) +``` + +Copies the sign of one number to another. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number whose magnitude will be copied. | +y | `Num` | The number whose sign will be copied. | + +**Return:** A number with the magnitude of `x` and the sign of `y`. + + +**Example:** +```tomo +>> (3.0).copysign(-1) += -3 + +``` +## Num.cos + +```tomo +Num.cos : func(x: Num -> Num) +``` + +Computes the cosine of a number (angle in radians). + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The angle in radians. | + +**Return:** The cosine of `x`. + + +**Example:** +```tomo +>> (0.0).cos() += 1 + +``` +## Num.cosh + +```tomo +Num.cosh : func(x: Num -> Num) +``` + +Computes the hyperbolic cosine of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the hyperbolic cosine is to be calculated. | + +**Return:** The hyperbolic cosine of `x`. + + +**Example:** +```tomo +>> (0.0).cosh() += 1 + +``` +## Num.erf + +```tomo +Num.erf : func(x: Num -> Num) +``` + +Computes the error function of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the error function is to be calculated. | + +**Return:** The error function of `x`. + + +**Example:** +```tomo +>> (0.0).erf() += 0 + +``` +## Num.erfc + +```tomo +Num.erfc : func(x: Num -> Num) +``` + +Computes the complementary error function of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the complementary error function is to be calculated. | + +**Return:** The complementary error function of `x`. + + +**Example:** +```tomo +>> (0.0).erfc() += 1 + +``` +## Num.exp + +```tomo +Num.exp : func(x: Num -> Num) +``` + +Computes the exponential function $e^x$ for a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The exponent. | + +**Return:** The value of $e^x$. + + +**Example:** +```tomo +>> (1.0).exp() += 2.7183 + +``` +## Num.exp2 + +```tomo +Num.exp2 : func(x: Num -> Num) +``` + +Computes $2^x$ for a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The exponent. | + +**Return:** The value of $2^x$. + + +**Example:** +```tomo +>> (3.0).exp2() += 8 + +``` +## Num.expm1 + +```tomo +Num.expm1 : func(x: Num -> Num) +``` + +Computes $e^x - 1$ for a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The exponent. | + +**Return:** The value of $e^x - 1$. + + +**Example:** +```tomo +>> (1.0).expm1() += 1.7183 + +``` +## Num.fdim + +```tomo +Num.fdim : func(x: Num, y: Num -> Num) +``` + +Computes the positive difference between two numbers. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The first number. | +y | `Num` | The second number. | + +**Return:** The positive difference $\max(0, x - y)$. + + +**Example:** +```tomo +fd + +>> (5.0).fdim(3) += 2 + +``` +## Num.floor + +```tomo +Num.floor : func(x: Num -> Num) +``` + +Rounds a number down to the nearest integer. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number to be rounded down. | + +**Return:** The largest integer less than or equal to `x`. + + +**Example:** +```tomo +>> (3.7).floor() += 3 + +``` +## Num.format + +```tomo +Num.format : func(n: Num, precision: Int = 0 -> Text) +``` + +Formats a number as a text with a specified precision. + +Argument | Type | Description | Default +---------|------|-------------|--------- +n | `Num` | The number to be formatted. | +precision | `Int` | The number of decimal places. Default is `0`. | **Default:** `0` + +**Return:** A text representation of the number with the specified precision. + + +**Example:** +```tomo +>> (3.14159).format(precision=2) += "3.14" + +``` +## Num.hypot + +```tomo +Num.hypot : func(x: Num, y: Num -> Num) +``` + +Computes the Euclidean norm, $\sqrt{x^2 + y^2}$, of two numbers. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The first number. | +y | `Num` | The second number. | + +**Return:** The Euclidean norm of `x` and `y`. + + +**Example:** +```tomo +>> Num.hypot(3, 4) += 5 + +``` +## Num.is_between + +```tomo +Num.is_between : func(x: Num, low: Num, high: Num -> Bool) +``` + +Determines if a number is between two numbers (inclusive). + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The integer to be checked. | +low | `Num` | The lower bound to check (inclusive). | +high | `Num` | The upper bound to check (inclusive). | + +**Return:** `yes` if `low <= x and x <= high`, otherwise `no` + + +**Example:** +```tomo +>> (7.5).is_between(1, 10) += yes +>> (7.5).is_between(100, 200) += no +>> (7.5).is_between(1, 7.5) += yes + +``` +## Num.isfinite + +```tomo +Num.isfinite : func(n: Num -> Bool) +``` + +Checks if a number is finite. + +Argument | Type | Description | Default +---------|------|-------------|--------- +n | `Num` | The number to be checked. | + +**Return:** `yes` if `n` is finite, `no` otherwise. + + +**Example:** +```tomo +>> (1.0).isfinite() += yes +>> Num.INF.isfinite() += no + +``` +## Num.isinf + +```tomo +Num.isinf : func(n: Num -> Bool) +``` + +Checks if a number is infinite. + +Argument | Type | Description | Default +---------|------|-------------|--------- +n | `Num` | The number to be checked. | + +**Return:** `yes` if `n` is infinite, `no` otherwise. + + +**Example:** +```tomo +>> Num.INF.isinf() += yes +>> (1.0).isinf() += no + +``` +## Num.j0 + +```tomo +Num.j0 : func(x: Num -> Num) +``` + +Computes the Bessel function of the first kind of order 0. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the Bessel function is to be calculated. | + +**Return:** The Bessel function of the first kind of order 0 of `x`. + + +**Example:** +```tomo +>> (0.0).j0() += 1 + +``` +## Num.j1 + +```tomo +Num.j1 : func(x: Num -> Num) +``` + +Computes the Bessel function of the first kind of order 1. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the Bessel function is to be calculated. | + +**Return:** The Bessel function of the first kind of order 1 of `x`. + + +**Example:** +```tomo +>> (0.0).j1() += 0 + +``` +## Num.log + +```tomo +Num.log : func(x: Num -> Num) +``` + +Computes the natural logarithm (base $e$) of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the natural logarithm is to be calculated. | + +**Return:** The natural logarithm of `x`. + + +**Example:** +```tomo +>> Num.E.log() += 1 + +``` +## Num.log10 + +```tomo +Num.log10 : func(x: Num -> Num) +``` + +Computes the base-10 logarithm of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the base-10 logarithm is to be calculated. | + +**Return:** The base-10 logarithm of `x`. + + +**Example:** +```tomo +>> (100.0).log10() += 2 + +``` +## Num.log1p + +```tomo +Num.log1p : func(x: Num -> Num) +``` + +Computes $\log(1 + x)$ for a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which $\log(1 + x)$ is to be calculated. | + +**Return:** The value of $\log(1 + x)$. + + +**Example:** +```tomo +>> (1.0).log1p() += 0.6931 + +``` +## Num.log2 + +```tomo +Num.log2 : func(x: Num -> Num) +``` + +Computes the base-2 logarithm of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the base-2 logarithm is to be calculated. | + +**Return:** The base-2 logarithm of `x`. + + +**Example:** +```tomo +>> (8.0).log2() += 3 + +``` +## Num.logb + +```tomo +Num.logb : func(x: Num -> Num) +``` + +Computes the binary exponent (base-2 logarithm) of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the binary exponent is to be calculated. | + +**Return:** The binary exponent of `x`. + + +**Example:** +```tomo +>> (8.0).logb() += 3 + +``` +## Num.mix + +```tomo +Num.mix : func(amount: Num, x: Num, y: Num -> Num) +``` + +Interpolates between two numbers based on a given amount. + +Argument | Type | Description | Default +---------|------|-------------|--------- +amount | `Num` | The interpolation factor (between `0` and `1`). | +x | `Num` | The starting number. | +y | `Num` | The ending number. | + +**Return:** The interpolated number between `x` and `y` based on `amount`. + + +**Example:** +```tomo +>> (0.5).mix(10, 20) += 15 +>> (0.25).mix(10, 20) += 12.5 + +``` +## Num.near + +```tomo +Num.near : func(x: Num, y: Num, ratio: Num = 1e-9, min_epsilon: Num = 1e-9 -> Bool) +``` + +Checks if two numbers are approximately equal within specified tolerances. If two numbers are within an absolute difference or the ratio between the two is small enough, they are considered near each other. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The first number. | +y | `Num` | The second number. | +ratio | `Num` | The relative tolerance. Default is `1e-9`. | **Default:** `1e-9` +min_epsilon | `Num` | The absolute tolerance. Default is `1e-9`. | **Default:** `1e-9` + +**Return:** `yes` if `x` and `y` are approximately equal within the specified tolerances, `no` otherwise. + + +**Example:** +```tomo +>> (1.0).near(1.000000001) += yes + +>> (100.0).near(110, ratio=0.1) += yes + +>> (5.0).near(5.1, min_epsilon=0.1) += yes + +``` +## Num.nextafter + +```tomo +Num.nextafter : func(x: Num, y: Num -> Num) +``` + +Computes the next representable value after a given number towards a specified direction. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The starting number. | +y | `Num` | The direction towards which to find the next representable value. | + +**Return:** The next representable value after `x` in the direction of `y`. + + +**Example:** +```tomo +>> (1.0).nextafter(1.1) += 1.0000000000000002 + +``` +## Num.parse + +```tomo +Num.parse : func(text: Text -> Num?) +``` + +Converts a text representation of a number into a floating-point number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text containing the number. | + +**Return:** The number represented by the text or `none` if the entire text can't be parsed as a number. + + +**Example:** +```tomo +>> Num.parse("3.14") += 3.14 +>> Num.parse("1e3") += 1000 + +``` +## Num.percent + +```tomo +Num.percent : func(n: Num, precision: Int = 0 -> Text) +``` + +Convert a number into a percentage text with a percent sign. + +Argument | Type | Description | Default +---------|------|-------------|--------- +n | `Num` | The number to be converted to a percent. | +precision | `Int` | The number of decimal places. Default is `0`. | **Default:** `0` + +**Return:** A text representation of the number as a percentage with a percent sign. + + +**Example:** +```tomo +>> (0.5).percent() += "50%" +>> (1./3.).percent(2) += "33.33%" + +``` +## Num.rint + +```tomo +Num.rint : func(x: Num -> Num) +``` + +Rounds a number to the nearest integer, with ties rounded to the nearest even integer. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number to be rounded. | + +**Return:** The nearest integer value of `x`. + + +**Example:** +```tomo +>> (3.5).rint() += 4 +>> (2.5).rint() += 2 + +``` +## Num.round + +```tomo +Num.round : func(x: Num -> Num) +``` + +Rounds a number to the nearest whole number integer. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number to be rounded. | + +**Return:** The nearest integer value of `x`. + + +**Example:** +```tomo +>> (2.3).round() += 2 +>> (2.7).round() += 3 + +``` +## Num.scientific + +```tomo +Num.scientific : func(n: Num, precision: Int = 0 -> Text) +``` + +Formats a number in scientific notation with a specified precision. + +Argument | Type | Description | Default +---------|------|-------------|--------- +n | `Num` | The number to be formatted. | +precision | `Int` | The number of decimal places. Default is `0`. | **Default:** `0` + +**Return:** A text representation of the number in scientific notation with the specified precision. + + +**Example:** +```tomo +>> (12345.6789).scientific(precision=2) += "1.23e+04" + +``` +## Num.significand + +```tomo +Num.significand : func(x: Num -> Num) +``` + +Extracts the significand (or mantissa) of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number from which to extract the significand. | + +**Return:** The significand of `x`. + + +**Example:** +```tomo +>> (1234.567).significand() += 0.1234567 + +``` +## Num.sin + +```tomo +Num.sin : func(x: Num -> Num) +``` + +Computes the sine of a number (angle in radians). + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The angle in radians. | + +**Return:** The sine of `x`. + + +**Example:** +```tomo +>> (0.0).sin() += 0 + +``` +## Num.sinh + +```tomo +Num.sinh : func(x: Num -> Num) +``` + +Computes the hyperbolic sine of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the hyperbolic sine is to be calculated. | + +**Return:** The hyperbolic sine of `x`. + + +**Example:** +```tomo +>> (0.0).sinh() += 0 + +``` +## Num.sqrt + +```tomo +Num.sqrt : func(x: Num -> Num) +``` + +Computes the square root of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the square root is to be calculated. | + +**Return:** The square root of `x`. + + +**Example:** +```tomo +>> (16.0).sqrt() += 4 + +``` +## Num.tan + +```tomo +Num.tan : func(x: Num -> Num) +``` + +Computes the tangent of a number (angle in radians). + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The angle in radians. | + +**Return:** The tangent of `x`. + + +**Example:** +```tomo +>> (0.0).tan() += 0 + +``` +## Num.tanh + +```tomo +Num.tanh : func(x: Num -> Num) +``` + +Computes the hyperbolic tangent of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the hyperbolic tangent is to be calculated. | + +**Return:** The hyperbolic tangent of `x`. + + +**Example:** +```tomo +>> (0.0).tanh() += 0 + +``` +## Num.tgamma + +```tomo +Num.tgamma : func(x: Num -> Num) +``` + +Computes the gamma function of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the gamma function is to be calculated. | + +**Return:** The gamma function of `x`. + + +**Example:** +```tomo +>> (1.0).tgamma() += 1 + +``` +## Num.trunc + +```tomo +Num.trunc : func(x: Num -> Num) +``` + +Truncates a number to the nearest integer towards zero. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number to be truncated. | + +**Return:** The integer part of `x` towards zero. + + +**Example:** +```tomo +>> (3.7).trunc() += 3 +>> (-3.7).trunc() += -3 + +``` +## Num.y0 + +```tomo +Num.y0 : func(x: Num -> Num) +``` + +Computes the Bessel function of the second kind of order 0. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the Bessel function is to be calculated. | + +**Return:** The Bessel function of the second kind of order 0 of `x`. + + +**Example:** +```tomo +>> (1.0).y0() += -0.7652 + +``` +## Num.y1 + +```tomo +Num.y1 : func(x: Num -> Num) +``` + +Computes the Bessel function of the second kind of order 1. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the Bessel function is to be calculated. | + +**Return:** The Bessel function of the second kind of order 1 of `x`. + + +**Example:** +```tomo +>> (1.0).y1() += 0.4401 + +``` + +# Path +## Path.accessed + +```tomo +Path.accessed : func(path: Path, follow_symlinks: Bool = yes -> Int64?) +``` + +Gets the file access time of a file. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file whose access time you want. | +follow_symlinks | `Bool` | Whether to follow symbolic links. | **Default:** `yes` + +**Return:** A 64-bit unix epoch timestamp representing when the file or directory was last accessed, or `none` if no such file or directory exists. + + +**Example:** +```tomo +>> (./file.txt).accessed() += 1704221100? +>> (./not-a-file).accessed() += none + +``` +## Path.append + +```tomo +Path.append : func(path: Path, text: Text, permissions: Int32 = Int32(0o644) -> Void) +``` + +Appends the given text to the file at the specified path, creating the file if it doesn't already exist. Failure to write will result in a runtime error. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file to append to. | +text | `Text` | The text to append to the file. | +permissions | `Int32` | The permissions to set on the file if it is being created. | **Default:** `Int32(0o644)` + +**Return:** Nothing. + + +**Example:** +```tomo +(./log.txt).append("extra line$(\n)") + +``` +## Path.append_bytes + +```tomo +Path.append_bytes : func(path: Path, bytes: [Byte], permissions: Int32 = Int32(0o644) -> Void) +``` + +Appends the given bytes to the file at the specified path, creating the file if it doesn't already exist. Failure to write will result in a runtime error. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file to append to. | +bytes | `[Byte]` | The bytes to append to the file. | +permissions | `Int32` | The permissions to set on the file if it is being created. | **Default:** `Int32(0o644)` + +**Return:** Nothing. + + +**Example:** +```tomo +(./log.txt).append_bytes([104, 105]) + +``` +## Path.base_name + +```tomo +Path.base_name : func(path: Path -> Text) +``` + +Returns the base name of the file or directory at the specified path. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file or directory. | + +**Return:** The base name of the file or directory. + + +**Example:** +```tomo +>> (./path/to/file.txt).base_name() += "file.txt" + +``` +## Path.by_line + +```tomo +Path.by_line : func(path: Path -> func(->Text?)?) +``` + +Returns an iterator that can be used to iterate over a file one line at a time, or returns a null value if the file could not be opened. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file. | + +**Return:** An iterator that can be used to get lines from a file one at a time or a null value if the file couldn't be read. + + +**Example:** +```tomo +# Safely handle file not being readable: +if lines := (./file.txt).by_line() +for line in lines +say(line.upper()) +else +say("Couldn't read file!") + +# Assume the file is readable and error if that's not the case: +for line in (/dev/stdin).by_line()! +say(line.upper()) + +``` +## Path.can_execute + +```tomo +Path.can_execute : func(path: Path -> Bool) +``` + +Returns whether or not a file can be executed by the current user/group. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file to check. | + +**Return:** `yes` if the file or directory exists and the current user has execute permissions, otherwise `no`. + + +**Example:** +```tomo +>> (/bin/sh).can_execute() += yes +>> (/usr/include/stdlib.h).can_execute() += no +>> (/non/existant/file).can_execute() += no + +``` +## Path.can_read + +```tomo +Path.can_read : func(path: Path -> Bool) +``` + +Returns whether or not a file can be read by the current user/group. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file to check. | + +**Return:** `yes` if the file or directory exists and the current user has read permissions, otherwise `no`. + + +**Example:** +```tomo +>> (/usr/include/stdlib.h).can_read() += yes +>> (/etc/shadow).can_read() += no +>> (/non/existant/file).can_read() += no + +``` +## Path.can_write + +```tomo +Path.can_write : func(path: Path -> Bool) +``` + +Returns whether or not a file can be written by the current user/group. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file to check. | + +**Return:** `yes` if the file or directory exists and the current user has write permissions, otherwise `no`. + + +**Example:** +```tomo +>> (/tmp).can_write() += yes +>> (/etc/passwd).can_write() += no +>> (/non/existant/file).can_write() += no + +``` +## Path.changed + +```tomo +Path.changed : func(path: Path, follow_symlinks: Bool = yes -> Int64?) +``` + +Gets the file change time of a file. + +This is the ["ctime"](https://en.wikipedia.org/wiki/Stat_(system_call)#ctime) of a file, which is _not_ the file creation time. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file whose change time you want. | +follow_symlinks | `Bool` | Whether to follow symbolic links. | **Default:** `yes` + +**Return:** A 64-bit unix epoch timestamp representing when the file or directory was last changed, or `none` if no such file or directory exists. + + +**Example:** +```tomo +>> (./file.txt).changed() += 1704221100? +>> (./not-a-file).changed() += none + +``` +## Path.child + +```tomo +Path.child : func(path: Path, child: Text -> [Path]) +``` + +Return a path that is a child of another path. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of a directory. | +child | `Text` | The name of a child file or directory. | + +**Return:** A new path representing the child. + + +**Example:** +```tomo +>> (./directory).child("file.txt") += (./directory/file.txt) + +``` +## Path.children + +```tomo +Path.children : func(path: Path, include_hidden = no -> [Path]) +``` + +Returns a list of children (files and directories) within the directory at the specified path. Optionally includes hidden files. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the directory. | +include_hidden | `` | Whether to include hidden files, which start with a `.`. | **Default:** `no` + +**Return:** A list of paths for the children. + + +**Example:** +```tomo +>> (./directory).children(include_hidden=yes) += [".git", "foo.txt"] + +``` +## Path.create_directory + +```tomo +Path.create_directory : func(path: Path, permissions = Int32(0o755) -> Void) +``` + +Creates a new directory at the specified path with the given permissions. If any of the parent directories do not exist, they will be created as needed. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the directory to create. | +permissions | `` | The permissions to set on the new directory. | **Default:** `Int32(0o755)` + +**Return:** Nothing. + + +**Example:** +```tomo +(./new_directory).create_directory() + +``` +## Path.current_dir + +```tomo +Path.current_dir : func(-> Path) +``` + +Creates a new directory at the specified path with the given permissions. If any of the parent directories do not exist, they will be created as needed. + + +**Return:** The absolute path of the current directory. + + +**Example:** +```tomo +>> Path.current_dir() += (/home/user/tomo) + +``` +## Path.exists + +```tomo +Path.exists : func(path: Path -> Bool) +``` + +Checks if a file or directory exists at the specified path. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path to check. | + +**Return:** `True` if the file or directory exists, `False` otherwise. + + +**Example:** +```tomo +>> (/).exists() += yes + +``` +## Path.expand_home + +```tomo +Path.expand_home : func(path: Path -> Path) +``` + +For home-based paths (those starting with `~`), expand the path to replace the tilde with and absolute path to the user's `$HOME` directory. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path to expand. | + +**Return:** If the path does not start with a `~`, then return it unmodified. Otherwise, replace the `~` with an absolute path to the user's home directory. + + +**Example:** +```tomo +>> (~/foo).expand_home() # Assume current user is 'user' += /home/user/foo +>> (/foo).expand_home() # No change += /foo + +``` +## Path.extension + +```tomo +Path.extension : func(path: Path, full: Bool = yes -> Text) +``` + +Returns the file extension of the file at the specified path. Optionally returns the full extension. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file. | +full | `Bool` | Whether to return everything after the first `.` in the base name, or only the last part of the extension. | **Default:** `yes` + +**Return:** The file extension (not including the leading `.`) or an empty text if there is no file extension. + + +**Example:** +```tomo +>> (./file.tar.gz).extension() += "tar.gz" +>> (./file.tar.gz).extension(full=no) += "gz" +>> (/foo).extension() += "" +>> (./.git).extension() += "" + +``` +## Path.files + +```tomo +Path.files : func(path: Path, include_hidden: Bool = no -> [Path]) +``` + +Returns a list of files within the directory at the specified path. Optionally includes hidden files. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the directory. | +include_hidden | `Bool` | Whether to include hidden files. | **Default:** `no` + +**Return:** A list of file paths. + + +**Example:** +```tomo +>> (./directory).files(include_hidden=yes) += [(./directory/file1.txt), (./directory/file2.txt)] + +``` +## Path.from_components + +```tomo +Path.from_components : func(components: [Text] -> Path) +``` + +Returns a path built from a list of path components. + +Argument | Type | Description | Default +---------|------|-------------|--------- +components | `[Text]` | A list of path components. | + +**Return:** A path representing the given components. + + +**Example:** +```tomo +>> Path.from_components(["/", "usr", "include"]) += /usr/include +>> Path.from_components(["foo.txt"]) += ./foo.txt +>> Path.from_components(["~", ".local"]) += ~/.local + +``` +## Path.glob + +```tomo +Path.glob : func(path: Path -> [Path]) +``` + +Perform a globbing operation and return a list of matching paths. Some glob specific details: +- The paths "." and ".." are *not* included in any globbing results. +- Files or directories that begin with "." will not match `*`, but will match `.*`. +- Globs do support `{a,b}` syntax for matching files that match any of several + choices of patterns. + +- The shell-style syntax `**` for matching subdirectories is not supported. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the directory which may contain special globbing characters like `*`, `?`, or `{...}` | + +**Return:** A list of file paths that match the glob. + + +**Example:** +```tomo +# Current directory includes: foo.txt, baz.txt, qux.jpg, .hidden +>> (./*).glob() += [(./foo.txt), (./baz.txt), (./qux.jpg)] + +>> (./*.txt).glob() += [(./foo.txt), (./baz.txt)] + +>> (./*.{txt,jpg}).glob() += [(./foo.txt), (./baz.txt), (./qux.jpg)] + +>> (./.*).glob() += [(./.hidden)] + +# Globs with no matches return an empty list: +>> (./*.xxx).glob() += [] + +``` +## Path.group + +```tomo +Path.group : func(path: Path, follow_symlinks: Bool = yes -> Text?) +``` + +Get the owning group of a file or directory. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path whose owning group to get. | +follow_symlinks | `Bool` | Whether to follow symbolic links. | **Default:** `yes` + +**Return:** The name of the group which owns the file or directory, or `none` if the path does not exist. + + +**Example:** +```tomo +>> (/bin).group() += "root" +>> (/non/existent/file).group() += none + +``` +## Path.is_directory + +```tomo +Path.is_directory : func(path: Path, follow_symlinks = yes -> Bool) +``` + +Checks if the path represents a directory. Optionally follows symbolic links. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path to check. | +follow_symlinks | `` | Whether to follow symbolic links. | **Default:** `yes` + +**Return:** `True` if the path is a directory, `False` otherwise. + + +**Example:** +```tomo +>> (./directory/).is_directory() += yes + +>> (./file.txt).is_directory() += no + +``` +## Path.is_file + +```tomo +Path.is_file : func(path: Path, follow_symlinks = yes -> Bool) +``` + +Checks if the path represents a file. Optionally follows symbolic links. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path to check. | +follow_symlinks | `` | Whether to follow symbolic links. | **Default:** `yes` + +**Return:** `True` if the path is a file, `False` otherwise. + + +**Example:** +```tomo +>> (./file.txt).is_file() += yes + +>> (./directory/).is_file() += no + +``` +## Path.is_socket + +```tomo +Path.is_socket : func(path: Path, follow_symlinks = yes -> Bool) +``` + +Checks if the path represents a socket. Optionally follows symbolic links. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path to check. | +follow_symlinks | `` | Whether to follow symbolic links. | **Default:** `yes` + +**Return:** `True` if the path is a socket, `False` otherwise. + + +**Example:** +```tomo +>> (./socket).is_socket() += yes + +``` +## Path.is_symlink + +```tomo +Path.is_symlink : func(path: Path -> Bool) +``` + +Checks if the path represents a symbolic link. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path to check. | + +**Return:** `True` if the path is a symbolic link, `False` otherwise. + + +**Example:** +```tomo +>> (./link).is_symlink() += yes + +``` +## Path.modified + +```tomo +Path.modified : func(path: Path, follow_symlinks: Bool = yes -> Int64?) +``` + +Gets the file modification time of a file. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file whose modification time you want. | +follow_symlinks | `Bool` | Whether to follow symbolic links. | **Default:** `yes` + +**Return:** A 64-bit unix epoch timestamp representing when the file or directory was last modified, or `none` if no such file or directory exists. + + +**Example:** +```tomo +>> (./file.txt).modified() += 1704221100? +>> (./not-a-file).modified() += none + +``` +## Path.owner + +```tomo +Path.owner : func(path: Path, follow_symlinks: Bool = yes -> Text?) +``` + +Get the owning user of a file or directory. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path whose owner to get. | +follow_symlinks | `Bool` | Whether to follow symbolic links. | **Default:** `yes` + +**Return:** The name of the user who owns the file or directory, or `none` if the path does not exist. + + +**Example:** +```tomo +>> (/bin).owner() += "root" +>> (/non/existent/file).owner() += none + +``` +## Path.parent + +```tomo +Path.parent : func(path: Path -> Path) +``` + +Returns the parent directory of the file or directory at the specified path. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file or directory. | + +**Return:** The path of the parent directory. + + +**Example:** +```tomo +>> (./path/to/file.txt).parent() += (./path/to/) + +``` +## Path.read + +```tomo +Path.read : func(path: Path -> Text?) +``` + +Reads the contents of the file at the specified path or a null value if the file could not be read. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file to read. | + +**Return:** The contents of the file. If the file could not be read, a null value will be returned. If the file can be read, but is not valid UTF8 data, an error will be raised. + + +**Example:** +```tomo +>> (./hello.txt).read() += "Hello"? + +>> (./nosuchfile.xxx).read() += none + +``` +## Path.read_bytes + +```tomo +Path.read_bytes : func(path: Path, limit: Int? = none -> [Byte]?) +``` + +Reads the contents of the file at the specified path or a null value if the file could not be read. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file to read. | +limit | `Int?` | A limit to how many bytes should be read. | **Default:** `none` + +**Return:** The byte contents of the file. If the file cannot be read, a null value will be returned. + + +**Example:** +```tomo +>> (./hello.txt).read() += [72, 101, 108, 108, 111]? + +>> (./nosuchfile.xxx).read() += none + +``` +## Path.relative_to + +```tomo +Path.relative_to : func(path: Path, relative_to = (./) -> Path) +``` + +Returns the path relative to a given base path. By default, the base path is the current directory. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path to convert. | +relative_to | `` | The base path for the relative path. | **Default:** `(./)` + +**Return:** The relative path. + + +**Example:** +```tomo +>> (./path/to/file.txt).relative(relative_to=(./path)) += (./to/file.txt) + +``` +## Path.remove + +```tomo +Path.remove : func(path: Path, ignore_missing = no -> Void) +``` + +Removes the file or directory at the specified path. A runtime error is raised if something goes wrong. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path to remove. | +ignore_missing | `` | Whether to ignore errors if the file or directory does not exist. | **Default:** `no` + +**Return:** Nothing. + + +**Example:** +```tomo +(./file.txt).remove() + +``` +## Path.resolved + +```tomo +Path.resolved : func(path: Path, relative_to = (./) -> Path) +``` + +Resolves the absolute path of the given path relative to a base path. By default, the base path is the current directory. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path to resolve. | +relative_to | `` | The base path for resolution. | **Default:** `(./)` + +**Return:** The resolved absolute path. + + +**Example:** +```tomo +>> (~/foo).resolved() += (/home/user/foo) + +>> (./path/to/file.txt).resolved(relative_to=(/foo)) += (/foo/path/to/file.txt) + +``` +## Path.set_owner + +```tomo +Path.set_owner : func(path: Path, owner: Text? = none, group: Text? = none, follow_symlinks: Bool = yes -> Void) +``` + +Set the owning user and/or group for a path. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path to change the permissions for. | +owner | `Text?` | If non-none, the new user to assign to be the owner of the file. | **Default:** `none` +group | `Text?` | If non-none, the new group to assign to be the owner of the file. | **Default:** `none` +follow_symlinks | `Bool` | Whether to follow symbolic links. | **Default:** `yes` + +**Return:** Nothing. If a path does not exist, a failure will be raised. + + +**Example:** +```tomo +(./file.txt).set_owner(owner="root", group="wheel") + +``` +## Path.subdirectories + +```tomo +Path.subdirectories : func(path: Path, include_hidden = no -> [Path]) +``` + +Returns a list of subdirectories within the directory at the specified path. Optionally includes hidden subdirectories. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the directory. | +include_hidden | `` | Whether to include hidden subdirectories. | **Default:** `no` + +**Return:** A list of subdirectory paths. + + +**Example:** +```tomo +>> (./directory).subdirectories() += [(./directory/subdir1), (./directory/subdir2)] + +>> (./directory).subdirectories(include_hidden=yes) += [(./directory/.git), (./directory/subdir1), (./directory/subdir2)] + +``` +## Path.unique_directory + +```tomo +Path.unique_directory : func(path: Path -> Path) +``` + +Generates a unique directory path based on the given path. Useful for creating temporary directories. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The base path for generating the unique directory. The last six letters of this path must be `XXXXXX`. | + +**Return:** A unique directory path after creating the directory. + + +**Example:** +```tomo +>> created := (/tmp/my-dir.XXXXXX).unique_directory() += (/tmp/my-dir-AwoxbM/) +>> created.is_directory() += yes +created.remove() + +``` +## Path.write + +```tomo +Path.write : func(path: Path, text: Text, permissions = Int32(0o644) -> Void) +``` + +Writes the given text to the file at the specified path, creating the file if it doesn't already exist. Sets the file permissions as specified. If the file writing cannot be successfully completed, a runtime error is raised. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file to write to. | +text | `Text` | The text to write to the file. | +permissions | `` | The permissions to set on the file if it is created. | **Default:** `Int32(0o644)` + +**Return:** Nothing. + + +**Example:** +```tomo +(./file.txt).write("Hello, world!") + +``` +## Path.write_bytes + +```tomo +Path.write_bytes : func(path: Path, bytes: [Byte], permissions = Int32(0o644) -> Void) +``` + +Writes the given bytes to the file at the specified path, creating the file if it doesn't already exist. Sets the file permissions as specified. If the file writing cannot be successfully completed, a runtime error is raised. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file to write to. | +bytes | `[Byte]` | A list of bytes to write to the file. | +permissions | `` | The permissions to set on the file if it is created. | **Default:** `Int32(0o644)` + +**Return:** Nothing. + + +**Example:** +```tomo +(./file.txt).write_bytes([104, 105]) + +``` +## Path.write_unique + +```tomo +Path.write_unique : func(path: Path, text: Text -> Path) +``` + +Writes the given text to a unique file path based on the specified path. The file is created if it doesn't exist. This is useful for creating temporary files. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The base path for generating the unique file. This path must include the string `XXXXXX` in the file base name. | +text | `Text` | The text to write to the file. | + +**Return:** The path of the newly created unique file. + + +**Example:** +```tomo +>> created := (./file-XXXXXX.txt).write_unique("Hello, world!") += (./file-27QHtq.txt) +>> created.read() += "Hello, world!" +created.remove() + +``` +## Path.write_unique_bytes + +```tomo +Path.write_unique_bytes : func(path: Path, bytes: [Byte] -> Path) +``` + +Writes the given bytes to a unique file path based on the specified path. The file is created if it doesn't exist. This is useful for creating temporary files. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The base path for generating the unique file. This path must include the string `XXXXXX` in the file base name. | +bytes | `[Byte]` | The bytes to write to the file. | + +**Return:** The path of the newly created unique file. + + +**Example:** +```tomo +>> created := (./file-XXXXXX.txt).write_unique_bytes([1, 2, 3]) += (./file-27QHtq.txt) +>> created.read() += [1, 2, 3] +created.remove() + +``` + +# Set +## Set.add + +```tomo +Set.add : func(set: |T|, item: T -> Void) +``` + +Adds an item to the set. + +Argument | Type | Description | Default +---------|------|-------------|--------- +set | `|T|` | The mutable reference to the set. | +item | `T` | The item to add to the set. | + +**Return:** Nothing. + + +**Example:** +```tomo +>> nums.add(42) + +``` +## Set.add_all + +```tomo +Set.add_all : func(set: @|T|, items: [T] -> Void) +``` + +Adds multiple items to the set. + +Argument | Type | Description | Default +---------|------|-------------|--------- +set | `@|T|` | The mutable reference to the set. | +items | `[T]` | The list of items to add to the set. | + +**Return:** Nothing. + + +**Example:** +```tomo +>> nums.add_all([1, 2, 3]) + +``` +## Set.clear + +```tomo +Set.clear : func(set: @|T| -> Void) +``` + +Removes all items from the set. + +Argument | Type | Description | Default +---------|------|-------------|--------- +set | `@|T|` | The mutable reference to the set. | + +**Return:** Nothing. + + +**Example:** +```tomo +>> nums.clear() + +``` +## Set.has + +```tomo +Set.has : func(set: |T|, item: T -> Bool) +``` + +Checks if the set contains a specified item. + +Argument | Type | Description | Default +---------|------|-------------|--------- +set | `|T|` | The set to check. | +item | `T` | The item to check for presence. | + +**Return:** `yes` if the item is present, `no` otherwise. + + +**Example:** +```tomo +>> |10, 20|.has(20) += yes + +``` +## Set.is_subset_of + +```tomo +Set.is_subset_of : func(set: |T|, other: |T|, strict: Bool = no -> Bool) +``` + +Checks if the set is a subset of another set. + +Argument | Type | Description | Default +---------|------|-------------|--------- +set | `|T|` | The set to check. | +other | `|T|` | The set to compare against. | +strict | `Bool` | If `yes`, checks if the set is a strict subset (does not equal the other set). | **Default:** `no` + +**Return:** `yes` if the set is a subset of the other set (strictly or not), `no` otherwise. + + +**Example:** +```tomo +>> |1, 2|.is_subset_of(|1, 2, 3|) += yes + +``` +## Set.is_superset_of + +```tomo +Set.is_superset_of : func(set: |T|, other: |T|, strict: Bool = no -> Bool) +``` + +Checks if the set is a superset of another set. + +Argument | Type | Description | Default +---------|------|-------------|--------- +set | `|T|` | The set to check. | +other | `|T|` | The set to compare against. | +strict | `Bool` | If `yes`, checks if the set is a strict superset (does not equal the other set). | **Default:** `no` + +**Return:** `yes` if the set is a superset of the other set (strictly or not), `no` otherwise. + + +**Example:** +```tomo +>> |1, 2, 3|.is_superset_of(|1, 2|) += yes + +``` +## Set.overlap + +```tomo +Set.overlap : func(set: |T|, other: |T| -> |T|) +``` + +Creates a new set with items that are in both the original set and another set. + +Argument | Type | Description | Default +---------|------|-------------|--------- +set | `|T|` | The original set. | +other | `|T|` | The set to intersect with. | + +**Return:** A new set containing only items present in both sets. + + +**Example:** +```tomo +>> |1, 2|.overlap(|2, 3|) += |2| + +``` +## Set.remove + +```tomo +Set.remove : func(set: @|T|, item: T -> Void) +``` + +Removes an item from the set. + +Argument | Type | Description | Default +---------|------|-------------|--------- +set | `@|T|` | The mutable reference to the set. | +item | `T` | The item to remove from the set. | + +**Return:** Nothing. + + +**Example:** +```tomo +>> nums.remove(42) + +``` +## Set.remove_all + +```tomo +Set.remove_all : func(set: @|T|, items: [T] -> Void) +``` + +Removes multiple items from the set. + +Argument | Type | Description | Default +---------|------|-------------|--------- +set | `@|T|` | The mutable reference to the set. | +items | `[T]` | The list of items to remove from the set. | + +**Return:** Nothing. + + +**Example:** +```tomo +>> nums.remove_all([1, 2, 3]) + +``` +## Set.with + +```tomo +Set.with : func(set: |T|, other: |T| -> |T|) +``` + +Creates a new set that is the union of the original set and another set. + +Argument | Type | Description | Default +---------|------|-------------|--------- +set | `|T|` | The original set. | +other | `|T|` | The set to union with. | + +**Return:** A new set containing all items from both sets. + + +**Example:** +```tomo +>> |1, 2|.with(|2, 3|) += |1, 2, 3| + +``` +## Set.without + +```tomo +Set.without : func(set: |T|, other: |T| -> |T|) +``` + +Creates a new set with items from the original set but without items from another set. + +Argument | Type | Description | Default +---------|------|-------------|--------- +set | `|T|` | The original set. | +other | `|T|` | The set of items to remove from the original set. | + +**Return:** A new set containing items from the original set excluding those in the other set. + + +**Example:** +```tomo +>> |1, 2|.without(|2, 3|) += |1| + +``` + +# Table +## Table.clear + +```tomo +Table.clear : func(t: &{K=V} -> Void) +``` + +Removes all key-value pairs from the table. + +Argument | Type | Description | Default +---------|------|-------------|--------- +t | `&{K=V}` | The reference to the table. | + +**Return:** Nothing. + + +**Example:** +```tomo +>> t.clear() + +``` +## Table.get + +```tomo +Table.get : func(t: {K=V}, key: K -> V?) +``` + +Retrieves the value associated with a key, or returns `none` if the key is not present. **Note:** default values for the table are ignored. + +Argument | Type | Description | Default +---------|------|-------------|--------- +t | `{K=V}` | The table. | +key | `K` | The key whose associated value is to be retrieved. | + +**Return:** The value associated with the key or `none` if the key is not found. + + +**Example:** +```tomo +>> t := {"A"=1, "B"=2} +>> t.get("A") += 1? + +>> t.get("????") += none + +>> t.get("A")! += 1 + +>> t.get("????") or 0 += 0 + +``` +## Table.get_or_set + +```tomo +Table.get_or_set : func(t: &{K=V}, key: K, default: V -> V?) +``` + +If the given key is in the table, return the associated value. Otherwise, insert the given default value into the table and return it. + +If no default value is provided explicitly, but the table has a default value associated with it, the table's default value will be used. +The default value is only evaluated if the key is missing. + +Argument | Type | Description | Default +---------|------|-------------|--------- +t | `&{K=V}` | The table. | +key | `K` | The key whose associated value is to be retrieved. | +default | `V` | The default value to insert and return if the key is not present in the table. | + +**Return:** Either the value associated with the key (if present) or the default value. The table will be mutated if the key is not already present. + + +**Example:** +```tomo +>> t := &{"A"=@[1, 2, 3]; default=@[]} +>> t.get_or_set("A").insert(4) +>> t.get_or_set("B").insert(99) +>> t += &{"A"=@[1, 2, 3, 4], "B"=@[99]} + +>> t.get_or_set("C", @[0, 0, 0]) += @[0, 0, 0] +>> t += &{"A"=@[1, 2, 3, 4], "B"=@[99], "C"=@[0, 0, 0]} + +``` +## Table.has + +```tomo +Table.has : func(t: {K=V}, key: K -> Bool) +``` + +Checks if the table contains a specified key. + +Argument | Type | Description | Default +---------|------|-------------|--------- +t | `{K=V}` | The table. | +key | `K` | The key to check for presence. | + +**Return:** `yes` if the key is present, `no` otherwise. + + +**Example:** +```tomo +>> {"A"=1, "B"=2}.has("A") += yes +>> {"A"=1, "B"=2}.has("xxx") += no + +``` +## Table.remove + +```tomo +Table.remove : func(t: {K=V}, key: K -> Void) +``` + +Removes the key-value pair associated with a specified key. + +Argument | Type | Description | Default +---------|------|-------------|--------- +t | `{K=V}` | The reference to the table. | +key | `K` | The key of the key-value pair to remove. | + +**Return:** Nothing. + + +**Example:** +```tomo +t := {"A"=1, "B"=2} +t.remove("A") +>> t += {"B"=2} + +``` +## Table.set + +```tomo +Table.set : func(t: {K=V}, key: K, value: V -> Void) +``` + +Sets or updates the value associated with a specified key. + +Argument | Type | Description | Default +---------|------|-------------|--------- +t | `{K=V}` | The reference to the table. | +key | `K` | The key to set or update. | +value | `V` | The value to associate with the key. | + +**Return:** Nothing. + + +**Example:** +```tomo +t := {"A"=1, "B"=2} +t.set("C", 3) +>> t += {"A"=1, "B"=2, "C"=3} + +``` + +# Text +## Text.as_c_string + +```tomo +Text.as_c_string : func(text: Text -> CString) +``` + +Converts a `Text` value to a C-style string. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be converted to a C-style string. | + +**Return:** A C-style string (`CString`) representing the text. + + +**Example:** +```tomo +>> "Hello".as_c_string() += CString("Hello") + +``` +## Text.at + +```tomo +Text.at : func(text: Text, index: Int -> Text) +``` + +Get the graphical cluster at a given index. This is similar to `str[i]` with ASCII text, but has more correct behavior for unicode text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text from which to get a cluster. | +index | `Int` | The index of the graphical cluster (1-indexed). | + +**Return:** A `Text` with the single graphical cluster at the given index. Note: negative indices are counted from the back of the text, so `-1` means the last cluster, `-2` means the second-to-last, and so on. + + +**Example:** +```tomo +>> "Amélie".at(3) += "é" + +``` +## Text.by_line + +```tomo +Text.by_line : func(text: Text -> func(->Text?)) +``` + +Returns an iterator function that can be used to iterate over the lines in a text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be iterated over, line by line. | + +**Return:** An iterator function that returns one line at a time, until it runs out and returns `none`. **Note:** this function ignores a trailing newline if there is one. If you don't want this behavior, use `text.by_split($/{1 nl}/)` instead. + + +**Example:** +```tomo +text := " +line one +line two +" +for line in text.by_line() +# Prints: "line one" then "line two": +say(line) + +``` +## Text.by_split + +```tomo +Text.by_split : func(text: Text, delimiter: Text = "" -> func(->Text?)) +``` + +Returns an iterator function that can be used to iterate over text separated by a delimiter. **Note:** to split based on a set of delimiters, use [`by_split_any()`](#by_split_any). + +If an empty text is given as the delimiter, then each split will be the graphical clusters of the text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be iterated over in delimited chunks. | +delimiter | `Text` | An exact delimiter to use for splitting the text. | **Default:** `""` + +**Return:** An iterator function that returns one chunk of text at a time, separated by the given delimiter, until it runs out and returns `none`. **Note:** using an empty delimiter (the default) will iterate over single grapheme clusters in the text. + + +**Example:** +```tomo +text := "one,two,three" +for chunk in text.by_split(",") +# Prints: "one" then "two" then "three": +say(chunk) + +``` +## Text.by_split_any + +```tomo +Text.by_split_any : func(text: Text, delimiters: Text = " $\t\r\n" -> func(->Text?)) +``` + +Returns an iterator function that can be used to iterate over text separated by one or more characters (grapheme clusters) from a given text of delimiters. **Note:** to split based on an exact delimiter, use [`by_split()`](#by_split). + +Splitting will occur on every place where one or more of the grapheme clusters in `delimiters` occurs. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be iterated over in delimited chunks. | +delimiters | `Text` | Grapheme clusters to use for splitting the text. | **Default:** `" $\t\r\n"` + +**Return:** An iterator function that returns one chunk of text at a time, separated by the given delimiter characters, until it runs out and returns `none`. + + +**Example:** +```tomo +text := "one,two,;,three" +for chunk in text.by_split_any(",;") +# Prints: "one" then "two" then "three": +say(chunk) + +``` +## Text.bytes + +```tomo +Text.bytes : func(text: Text -> [Byte]) +``` + +Converts a `Text` value to a list of bytes representing a UTF8 encoding of the text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be converted to UTF8 bytes. | + +**Return:** A list of bytes (`[Byte]`) representing the text in UTF8 encoding. + + +**Example:** +```tomo +>> "Amélie".bytes() += [65, 109, 195, 169, 108, 105, 101] + +``` +## Text.caseless_equals + +```tomo +Text.caseless_equals : func(a: Text, b: Text, language: Text = "C" -> Bool) +``` + +Checks whether two texts are equal, ignoring the casing of the letters (i.e. case-insensitive comparison). + +Argument | Type | Description | Default +---------|------|-------------|--------- +a | `Text` | The first text to compare case-insensitively. | +b | `Text` | The second text to compare case-insensitively. | +language | `Text` | The ISO 639 language code for which casing rules to use. | **Default:** `"C"` + +**Return:** `yes` if `a` and `b` are equal to each other, ignoring casing, otherwise `no`. + + +**Example:** +```tomo +>> "A".caseless_equals("a") += yes + +# Turkish lowercase "I" is "ı" (dotless I), not "i" +>> "I".caseless_equals("i", language="tr_TR") += no + +``` +## Text.codepoint_names + +```tomo +Text.codepoint_names : func(text: Text -> [Text]) +``` + +Returns a list of the names of each codepoint in the text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text from which to extract codepoint names. | + +**Return:** A list of codepoint names (`[Text]`). + + +**Example:** +```tomo +>> "Amélie".codepoint_names() += ["LATIN CAPITAL LETTER A", "LATIN SMALL LETTER M", "LATIN SMALL LETTER E WITH ACUTE", "LATIN SMALL LETTER L", "LATIN SMALL LETTER I", "LATIN SMALL LETTER E"] + +``` +## Text.ends_with + +```tomo +Text.ends_with : func(text: Text, suffix: Text -> Bool) +``` + +Checks if the `Text` ends with a literal suffix text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be searched. | +suffix | `Text` | The literal suffix text to check for. | + +**Return:** `yes` if the text has the target, `no` otherwise. + + +**Example:** +```tomo +>> "hello world".ends_with("world") += yes + +``` +## Text.from + +```tomo +Text.from : func(text: Text, first: Int -> Text) +``` + +Get a slice of the text, starting at the given position. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be sliced. | +first | `Int` | The index to begin the slice. | + +**Return:** The text from the given grapheme cluster to the end of the text. Note: a negative index counts backwards from the end of the text, so `-1` refers to the last cluster, `-2` the second-to-last, etc. Slice ranges will be truncated to the length of the text. + + +**Example:** +```tomo +>> "hello".from(2) += "ello" + +>> "hello".from(-2) += "lo" + +``` +## Text.from_bytes + +```tomo +Text.from_bytes : func(bytes: [Byte] -> [Text]) +``` + +Returns text that has been constructed from the given UTF8 bytes. Note: the text will be normalized, so the resulting text's UTF8 bytes may not exactly match the input. + +Argument | Type | Description | Default +---------|------|-------------|--------- +bytes | `[Byte]` | The UTF-8 bytes of the desired text. | + +**Return:** A new text based on the input UTF8 bytes after normalization has been applied. + + +**Example:** +```tomo +>> Text.from_bytes([195, 133, 107, 101]) += "Åke" + +``` +## Text.from_c_string + +```tomo +Text.from_c_string : func(str: CString -> Text) +``` + +Converts a C-style string to a `Text` value. + +Argument | Type | Description | Default +---------|------|-------------|--------- +str | `CString` | The C-style string to be converted. | + +**Return:** A `Text` value representing the C-style string. + + +**Example:** +```tomo +>> Text.from_c_string(CString("Hello")) += "Hello" + +``` +## Text.from_codepoint_names + +```tomo +Text.from_codepoint_names : func(codepoint_names: [Text] -> [Text]) +``` + +Returns text that has the given codepoint names (according to the Unicode specification) as its codepoints. Note: the text will be normalized, so the resulting text's codepoints may not exactly match the input codepoints. + +Argument | Type | Description | Default +---------|------|-------------|--------- +codepoint_names | `[Text]` | The names of each codepoint in the desired text (case-insentive). | + +**Return:** A new text with the specified codepoints after normalization has been applied. Any invalid names are ignored. + + +**Example:** +```tomo +>> Text.from_codepoint_names([ +"LATIN CAPITAL LETTER A WITH RING ABOVE", +"LATIN SMALL LETTER K", +"LATIN SMALL LETTER E", +] += "Åke" + +``` +## Text.from_codepoints + +```tomo +Text.from_codepoints : func(codepoints: [Int32] -> [Text]) +``` + +Returns text that has been constructed from the given UTF32 codepoints. Note: the text will be normalized, so the resulting text's codepoints may not exactly match the input codepoints. + +Argument | Type | Description | Default +---------|------|-------------|--------- +codepoints | `[Int32]` | The UTF32 codepoints in the desired text. | + +**Return:** A new text with the specified codepoints after normalization has been applied. + + +**Example:** +```tomo +>> Text.from_codepoints([197, 107, 101]) += "Åke" + +``` +## Text.has + +```tomo +Text.has : func(text: Text, target: Text -> Bool) +``` + +Checks if the `Text` contains some target text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be searched. | +target | `Text` | The text to search for. | + +**Return:** `yes` if the target text is found, `no` otherwise. + + +**Example:** +```tomo +>> "hello world".has("wo") += yes +>> "hello world".has("xxx") += no + +``` +## Text.join + +```tomo +Text.join : func(glue: Text, pieces: [Text] -> Text) +``` + +Joins a list of text pieces with a specified glue. + +Argument | Type | Description | Default +---------|------|-------------|--------- +glue | `Text` | The text used to join the pieces. | +pieces | `[Text]` | The list of text pieces to be joined. | + +**Return:** A single `Text` value with the pieces joined by the glue. + + +**Example:** +```tomo +>> ", ".join(["one", "two", "three"]) += "one, two, three" + +``` +## Text.left_pad + +```tomo +Text.left_pad : func(text: Text, width: Int, pad: Text = " ", language: Text = "C" -> Text) +``` + +Pad some text on the left side so it reaches a target width. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to pad. | +width | `Int` | The target width. | +pad | `Text` | The padding text. | **Default:** `" "` +language | `Text` | The ISO 639 language code for which character width to use. | **Default:** `"C"` + +**Return:** Text with length at least `width`, with extra padding on the left as needed. If `pad` has length greater than 1, it may be partially repeated to reach the exact desired length. + + +**Example:** +```tomo +>> "x".left_pad(5) += " x" +>> "x".left_pad(5, "ABC") += "ABCAx" + +``` +## Text.lines + +```tomo +Text.lines : func(text: Text -> [Text]) +``` + +Splits the text into a list of lines of text, preserving blank lines, ignoring trailing newlines, and handling `\r\n` the same as `\n`. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be split into lines. | + +**Return:** A list of substrings resulting from the split. + + +**Example:** +```tomo +>> "one\ntwo\nthree".lines() += ["one", "two", "three"] +>> "one\ntwo\nthree\n".lines() += ["one", "two", "three"] +>> "one\ntwo\nthree\n\n".lines() += ["one", "two", "three", ""] +>> "one\r\ntwo\r\nthree\r\n".lines() += ["one", "two", "three"] +>> "".lines() += [] + +``` +## Text.lower + +```tomo +Text.lower : func(text: Text, language: Text = "C" -> Text) +``` + +Converts all characters in the text to lowercase. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be converted to lowercase. | +language | `Text` | The ISO 639 language code for which casing rules to use. | **Default:** `"C"` + +**Return:** The lowercase version of the text. + + +**Example:** +```tomo +>> "AMÉLIE".lower() += "amélie" + +>> "I".lower(language="tr_TR") +>> "ı" + +``` +## Text.middle_pad + +```tomo +Text.middle_pad : func(text: Text, width: Int, pad: Text = " ", language: Text = "C" -> Text) +``` + +Pad some text on the left and right side so it reaches a target width. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to pad. | +width | `Int` | The target width. | +pad | `Text` | The padding text. | **Default:** `" "` +language | `Text` | The ISO 639 language code for which character width to use. | **Default:** `"C"` + +**Return:** Text with length at least `width`, with extra padding on the left and right as needed. If `pad` has length greater than 1, it may be partially repeated to reach the exact desired length. + + +**Example:** +```tomo +>> "x".middle_pad(6) += " x " +>> "x".middle_pad(10, "ABC") += "ABCAxABCAB" + +``` +## Text.quoted + +```tomo +Text.quoted : func(text: Text, color: Bool = no, quotation_mark: Text = `"` -> Text) +``` + +Formats the text with quotation marks and escapes. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be quoted. | +color | `Bool` | Whether to add color formatting. | **Default:** `no` +quotation_mark | `Text` | The quotation mark to use. | **Default:** ``"`` + +**Return:** The text formatted as a quoted text. + + +**Example:** +```tomo +>> "one\ntwo".quoted() += "\"one\\ntwo\"" + +``` +## Text.repeat + +```tomo +Text.repeat : func(text: Text, count: Int -> Text) +``` + +Repeat some text multiple times. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to repeat. | +count | `Int` | The number of times to repeat it. (Negative numbers are equivalent to zero). | + +**Return:** The text repeated the given number of times. + + +**Example:** +```tomo +>> "Abc".repeat(3) += "AbcAbcAbc" + +``` +## Text.replace + +```tomo +Text.replace : func(text: Text, target: Text, replacement: Text -> Text) +``` + +Replaces occurrences of a target text with a replacement text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text in which to perform replacements. | +target | `Text` | The target text to be replaced. | +replacement | `Text` | The text to replace the target with. | + +**Return:** The text with occurrences of the target replaced. + + +**Example:** +```tomo +>> "Hello world".replace("world", "there") += "Hello there" + +``` +## Text.reversed + +```tomo +Text.reversed : func(text: Text -> Text) +``` + +Return a text that has the grapheme clusters in reverse order. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to reverse. | + +**Return:** A reversed version of the text. + + +**Example:** +```tomo +>> "Abc".reversed() += "cbA" + +``` +## Text.right_pad + +```tomo +Text.right_pad : func(text: Text, width: Int, pad: Text = " ", language: Text = "C" -> Text) +``` + +Pad some text on the right side so it reaches a target width. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to pad. | +width | `Int` | The target width. | +pad | `Text` | The padding text. | **Default:** `" "` +language | `Text` | The ISO 639 language code for which character width to use. | **Default:** `"C"` + +**Return:** Text with length at least `width`, with extra padding on the right as needed. If `pad` has length greater than 1, it may be partially repeated to reach the exact desired length. + + +**Example:** +```tomo +>> "x".right_pad(5) += "x " +>> "x".right_pad(5, "ABC") += "xABCA" + +``` +## Text.slice + +```tomo +Text.slice : func(text: Text, from: Int = 1, to: Int = -1 -> Text) +``` + +Get a slice of the text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be sliced. | +from | `Int` | The index of the first grapheme cluster to include (1-indexed). | **Default:** `1` +to | `Int` | The index of the last grapheme cluster to include (1-indexed). | **Default:** `-1` + +**Return:** The text that spans the given grapheme cluster indices. Note: a negative index counts backwards from the end of the text, so `-1` refers to the last cluster, `-2` the second-to-last, etc. Slice ranges will be truncated to the length of the text. + + +**Example:** +```tomo +>> "hello".slice(2, 3) += "el" + +>> "hello".slice(to=-2) += "hell" + +>> "hello".slice(from=2) += "ello" + +``` +## Text.split + +```tomo +Text.split : func(text: Text, delimiter: Text = "" -> [Text]) +``` + +Splits the text into a list of substrings based on exact matches of a delimiter. **Note:** to split based on a set of delimiter characters, use [`split_any()`](#split_any). + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be split. | +delimiter | `Text` | The delimiter used to split the text. If the delimiter is the empty text, the text will be split into individual grapheme clusters. | **Default:** `""` + +**Return:** A list of subtexts resulting from the split. + + +**Example:** +```tomo +>> "one,two,,three".split(",") += ["one", "two", "", "three"] + +>> "abc".split() += ["a", "b", "c"] + +``` +## Text.split_any + +```tomo +Text.split_any : func(text: Text, delimiters: Text = " $\t\r\n" -> [Text]) +``` + +Splits the text into a list of substrings at one or more occurrences of a set of delimiter characters (grapheme clusters). **Note:** to split based on an exact delimiter, use [`split()`](#split). + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be split. | +delimiters | `Text` | A text containing multiple delimiters to be used for splitting the text into chunks. | **Default:** `" $\t\r\n"` + +**Return:** A list of subtexts resulting from the split. + + +**Example:** +```tomo +>> "one, two,,three".split_any(", ") += ["one", "two", "three"] + +``` +## Text.starts_with + +```tomo +Text.starts_with : func(text: Text, prefix: Text -> Bool) +``` + +Checks if the `Text` starts with a literal prefix text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be searched. | +prefix | `Text` | The literal prefix text to check for. | + +**Return:** `yes` if the text has the given prefix, `no` otherwise. + + +**Example:** +```tomo +>> "hello world".starts_with("hello") += yes + +``` +## Text.title + +```tomo +Text.title : func(text: Text, language: Text = "C" -> Text) +``` + +Converts the text to title case (capitalizing the first letter of each word). + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be converted to title case. | +language | `Text` | The ISO 639 language code for which casing rules to use. | **Default:** `"C"` + +**Return:** The text in title case. + + +**Example:** +```tomo +>> "amélie".title() += "Amélie" + +# In Turkish, uppercase "i" is "İ" +>> "i".title(language="tr_TR") += "İ" + +``` +## Text.to + +```tomo +Text.to : func(text: Text, last: Int -> Text) +``` + +Get a slice of the text, ending at the given position. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be sliced. | +last | `Int` | The index of the last grapheme cluster to include (1-indexed). | + +**Return:** The text up to and including the given grapheme cluster. Note: a negative index counts backwards from the end of the text, so `-1` refers to the last cluster, `-2` the second-to-last, etc. Slice ranges will be truncated to the length of the text. + + +**Example:** +```tomo +>> "goodbye".to(3) += "goo" + +>> "goodbye".to(-2) += "goodby" + +``` +## Text.translate + +```tomo +Text.translate : func(translations: {Text=Text} -> Text) +``` + +Takes a table mapping target texts to their replacements and performs all the replacements in the table on the whole text. At each position, the first matching replacement is applied and the matching moves on to *after* the replacement text, so replacement text is not recursively modified. See [`replace()`](#replace) for more information about replacement behavior. + +Argument | Type | Description | Default +---------|------|-------------|--------- +translations | `{Text=Text}` | A table mapping from target text to its replacement. | + +**Return:** The text with all occurrences of the targets replaced with their corresponding replacement text. + + +**Example:** +```tomo +>> "A & an amperand".translate({ +"&" = "&", +"<" = "<", +">" = ">", +'"" = """, +"'" = "'", +} += "A <tag> & an ampersand" + +``` +## Text.trim + +```tomo +Text.trim : func(text: Text, to_trim: Text = " $\t\r\n", left: Bool = yes, right: Bool = yes -> Text) +``` + +Trims the given characters (grapheme clusters) from the left and/or right side of the text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be trimmed. | +to_trim | `Text` | The characters to remove from the left/right of the text. | **Default:** `" $\t\r\n"` +left | `Bool` | Whether or not to trim from the front of the text. | **Default:** `yes` +right | `Bool` | Whether or not to trim from the back of the text. | **Default:** `yes` + +**Return:** The text without the trim characters at either end. + + +**Example:** +```tomo +>> " x y z \n".trim() += "x y z" + +>> "one,".trim(",") += "one" + +>> " xyz ".trim(right=no) += "xyz " + +``` +## Text.upper + +```tomo +Text.upper : func(text: Text, language: Text = "C" -> Text) +``` + +Converts all characters in the text to uppercase. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be converted to uppercase. | +language | `Text` | The ISO 639 language code for which casing rules to use. | **Default:** `"C"` + +**Return:** The uppercase version of the text. + + +**Example:** +```tomo +>> "amélie".upper() += "AMÉLIE" + +# In Turkish, uppercase "i" is "İ" +>> "i".upper(language="tr_TR") += "İ" + +``` +## Text.utf32_codepoints + +```tomo +Text.utf32_codepoints : func(text: Text -> [Int32]) +``` + +Returns a list of Unicode code points for UTF32 encoding of the text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text from which to extract Unicode code points. | + +**Return:** A list of 32-bit integer Unicode code points (`[Int32]`). + + +**Example:** +```tomo +>> "Amélie".utf32_codepoints() += [65, 109, 233, 108, 105, 101] + +``` +## Text.width + +```tomo +Text.width : func(text: Text -> Int) +``` + +Returns the display width of the text as seen in a terminal with appropriate font rendering. This is usually the same as the text's `.length`, but there are some characters like emojis that render wider than 1 cell. + +This will not always be exactly accurate when your terminal's font rendering can't handle some unicode displaying correctly. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text whose length you want. | + +**Return:** An integer representing the display width of the text. + + +**Example:** +```tomo +>> "Amélie".width() += 6 +>> "🤠".width() += 2 + +``` +## Text.without_prefix + +```tomo +Text.without_prefix : func(text: Text, prefix: Text -> Text) +``` + +Returns the text with a given prefix removed (if present). + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to remove the prefix from. | +prefix | `Text` | The prefix to remove. | + +**Return:** A text without the given prefix (if present) or the unmodified text if the prefix is not present. + + +**Example:** +```tomo +>> "foo:baz".without_prefix("foo:") += "baz" +>> "qux".without_prefix("foo:") += "qux" + +``` +## Text.without_suffix + +```tomo +Text.without_suffix : func(text: Text, suffix: Text -> Text) +``` + +Returns the text with a given suffix removed (if present). + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to remove the suffix from. | +suffix | `Text` | The suffix to remove. | + +**Return:** A text without the given suffix (if present) or the unmodified text if the suffix is not present. + + +**Example:** +```tomo +>> "baz.foo".without_suffix(".foo") += "baz" +>> "qux".without_suffix(".foo") += "qux" + +``` diff --git a/api/booleans.md b/api/booleans.md new file mode 100644 index 00000000..e6a01066 --- /dev/null +++ b/api/booleans.md @@ -0,0 +1,30 @@ +% API + +# Builtins + +# Bool +## Bool.parse + +```tomo +Bool.parse : func(text: Text -> Bool?) +``` + +Converts a string representation of a boolean value into a boolean. Acceptable boolean values are case-insensitive variations of `yes`/`no`, `y`/`n`, `true`/`false`, `on`/`off`. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The string containing the boolean value. | + +**Return:** `yes` if the string matches a recognized truthy boolean value; otherwise return `no`. + + +**Example:** +```tomo +>> Bool.parse("yes") += yes : Bool? +>> Bool.parse("no") += no : Bool? +>> Bool.parse("???") += none : Bool? + +``` diff --git a/api/booleans.yaml b/api/booleans.yaml new file mode 100644 index 00000000..851b7b0b --- /dev/null +++ b/api/booleans.yaml @@ -0,0 +1,22 @@ +Bool.parse: + description: > + Converts a string representation of a boolean value into a boolean. Acceptable + boolean values are case-insensitive variations of `yes`/`no`, `y`/`n`, + `true`/`false`, `on`/`off`. + return: + type: 'Bool?' + description: > + `yes` if the string matches a recognized truthy boolean value; otherwise return `no`. + args: + text: + type: 'Text' + description: > + The string containing the boolean value. + example: | + >> Bool.parse("yes") + = yes : Bool? + >> Bool.parse("no") + = no : Bool? + >> Bool.parse("???") + = none : Bool? + diff --git a/api/builtins.md b/api/builtins.md new file mode 100644 index 00000000..671849c3 --- /dev/null +++ b/api/builtins.md @@ -0,0 +1,183 @@ +% API + +# Builtins +## USE_COLOR + +```tomo +USE_COLOR : Bool +``` + +Whether or not the console prefers ANSI color escape sequences in the output. + +## ask + +```tomo +ask : func(prompt: Text, bold: Bool = yes, force_tty: Bool = yes -> Text?) +``` + +Gets a line of user input text with a prompt. + +When a program is receiving input from a pipe or writing its output to a pipe, this flag (which is enabled by default) forces the program to write the prompt to `/dev/tty` and read the input from `/dev/tty`, which circumvents the pipe. This means that `foo | ./tomo your-program | baz` will still show a visible prompt and read user input, despite the pipes. Setting this flag to `no` will mean that the prompt is written to `stdout` and input is read from `stdin`, even if those are pipes. + +Argument | Type | Description | Default +---------|------|-------------|--------- +prompt | `Text` | The text to print as a prompt before getting the input. | +bold | `Bool` | Whether or not to print make the prompt appear bold on a console. | **Default:** `yes` +force_tty | `Bool` | Whether or not to force the use of /dev/tty. | **Default:** `yes` + +**Return:** A line of user input text without a trailing newline, or empty text if something went wrong (e.g. the user hit `Ctrl-D`). + + +**Example:** +```tomo +>> ask("What's your name? ") += "Arthur Dent" + +``` +## exit + +```tomo +exit : func(message: Text? = !Text, status: Int32 = Int32(1) -> Void) +``` + +Exits the program with a given status and optionally prints a message. + +Argument | Type | Description | Default +---------|------|-------------|--------- +message | `Text?` | If nonempty, this message will be printed (with a newline) before exiting. | **Default:** `!Text` +status | `Int32` | The status code that the program with exit with. | **Default:** `Int32(1)` + +**Return:** This function never returns. + + +**Example:** +```tomo +exit(status=1, "Goodbye forever!") + +``` +## fail + +```tomo +fail : func(message: Text -> Abort) +``` + +Prints a message to the console, aborts the program, and prints a stack trace. + +Argument | Type | Description | Default +---------|------|-------------|--------- +message | `Text` | The error message to print. | + +**Return:** Nothing, aborts the program. + + +**Example:** +```tomo +fail("Oh no!") + +``` +## getenv + +```tomo +getenv : func(name: Text -> Text?) +``` + +Gets an environment variable. + +Argument | Type | Description | Default +---------|------|-------------|--------- +name | `Text` | The name of the environment variable to get. | + +**Return:** If set, the environment variable's value, otherwise, `none`. + + +**Example:** +```tomo +>> getenv("TERM") += "xterm-256color"? + +``` +## print + +```tomo +print : func(text: Text, newline: Bool = yes -> Void) +``` + +Prints a message to the console (alias for [`say`](#say)). + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to print. | +newline | `Bool` | Whether or not to print a newline after the text. | **Default:** `yes` + +**Return:** Nothing. + + +**Example:** +```tomo +print("Hello ", newline=no) +print("world!") + +``` +## say + +```tomo +say : func(text: Text, newline: Bool = yes -> Void) +``` + +Prints a message to the console. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to print. | +newline | `Bool` | Whether or not to print a newline after the text. | **Default:** `yes` + +**Return:** Nothing. + + +**Example:** +```tomo +say("Hello ", newline=no) +say("world!") + +``` +## setenv + +```tomo +setenv : func(name: Text, value: Text -> Void) +``` + +Sets an environment variable. + +Argument | Type | Description | Default +---------|------|-------------|--------- +name | `Text` | The name of the environment variable to set. | +value | `Text` | The new value of the environment variable. | + +**Return:** Nothing. + + +**Example:** +```tomo +setenv("FOOBAR", "xyz") + +``` +## sleep + +```tomo +sleep : func(seconds: Num -> Void) +``` + +Pause execution for a given number of seconds. + +Argument | Type | Description | Default +---------|------|-------------|--------- +seconds | `Num` | How many seconds to sleep for. | + +**Return:** Nothing. + + +**Example:** +```tomo +sleep(1.5) + +``` diff --git a/api/builtins.yaml b/api/builtins.yaml new file mode 100644 index 00000000..0f8e5bf1 --- /dev/null +++ b/api/builtins.yaml @@ -0,0 +1,168 @@ +ask: + description: > + Gets a line of user input text with a prompt. + note: > + When a program is receiving input from a pipe or writing its + output to a pipe, this flag (which is enabled by default) forces the program + to write the prompt to `/dev/tty` and read the input from `/dev/tty`, which + circumvents the pipe. This means that `foo | ./tomo your-program | baz` will + still show a visible prompt and read user input, despite the pipes. Setting + this flag to `no` will mean that the prompt is written to `stdout` and input + is read from `stdin`, even if those are pipes. + return: + type: 'Text?' + description: > + A line of user input text without a trailing newline, or empty text if + something went wrong (e.g. the user hit `Ctrl-D`). + args: + prompt: + type: 'Text' + description: > + The text to print as a prompt before getting the input. + bold: + type: 'Bool' + default: 'yes' + description: > + Whether or not to print make the prompt appear bold on a console. + force_tty: + type: 'Bool' + default: 'yes' + description: > + Whether or not to force the use of /dev/tty. + example: | + >> ask("What's your name? ") + = "Arthur Dent" + +exit: + description: > + Exits the program with a given status and optionally prints a message. + return: + type: 'Void' + description: > + This function never returns. + args: + message: + type: 'Text?' + default: '!Text' + description: > + If nonempty, this message will be printed (with a newline) before + exiting. + status: + type: 'Int32' + default: 'Int32(1)' + description: > + The status code that the program with exit with. + example: | + exit(status=1, "Goodbye forever!") + +getenv: + description: > + Gets an environment variable. + return: + type: 'Text?' + description: > + If set, the environment variable's value, otherwise, `none`. + args: + name: + type: 'Text' + description: > + The name of the environment variable to get. + example: | + >> getenv("TERM") + = "xterm-256color"? + +print: + description: > + Prints a message to the console (alias for [`say`](#say)). + return: + type: 'Void' + description: > + Nothing. + args: + text: + type: 'Text' + description: > + The text to print. + newline: + type: 'Bool' + default: 'yes' + description: > + Whether or not to print a newline after the text. + example: | + print("Hello ", newline=no) + print("world!") + +say: + description: > + Prints a message to the console. + return: + type: 'Void' + description: > + Nothing. + args: + text: + type: 'Text' + description: > + The text to print. + newline: + type: 'Bool' + default: 'yes' + description: > + Whether or not to print a newline after the text. + example: | + say("Hello ", newline=no) + say("world!") + +setenv: + description: > + Sets an environment variable. + return: + type: 'Void' + description: > + Nothing. + args: + name: + type: 'Text' + description: > + The name of the environment variable to set. + value: + type: 'Text' + description: > + The new value of the environment variable. + example: | + setenv("FOOBAR", "xyz") + +sleep: + description: > + Pause execution for a given number of seconds. + return: + type: 'Void' + description: > + Nothing. + args: + seconds: + type: 'Num' + description: > + How many seconds to sleep for. + example: | + sleep(1.5) + +fail: + description: > + Prints a message to the console, aborts the program, and prints a stack trace. + return: + type: 'Abort' + description: > + Nothing, aborts the program. + args: + message: + type: 'Text' + description: > + The error message to print. + example: | + fail("Oh no!") + +USE_COLOR: + type: Bool + description: > + Whether or not the console prefers ANSI color escape sequences in the output. diff --git a/api/bytes.md b/api/bytes.md new file mode 100644 index 00000000..1b61f166 --- /dev/null +++ b/api/bytes.md @@ -0,0 +1,108 @@ +% API + +# Builtins + +# Byte +## Byte.hex + +```tomo +Byte.hex : func(byte: Byte, uppercase: Bool = yes, prefix: Bool = no -> Text) +``` + +Convert a byte to a hexidecimal text representation. + +Argument | Type | Description | Default +---------|------|-------------|--------- +byte | `Byte` | The byte to convert to hex. | +uppercase | `Bool` | Whether or not to use uppercase hexidecimal letters. | **Default:** `yes` +prefix | `Bool` | Whether or not to prepend a `0x` prefix. | **Default:** `no` + +**Return:** The byte as a hexidecimal text. + + +**Example:** +```tomo +>> Byte(18).hex() += "0x12" + +``` +## Byte.is_between + +```tomo +Byte.is_between : func(x: Byte, low: Byte, high: Byte -> Bool) +``` + +Determines if an integer is between two numbers (inclusive). + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Byte` | The integer to be checked. | +low | `Byte` | The lower bound to check (inclusive). | +high | `Byte` | The upper bound to check (inclusive). | + +**Return:** `yes` if `low <= x and x <= high`, otherwise `no` + + +**Example:** +```tomo +>> Byte(7).is_between(1, 10) += yes +>> Byte(7).is_between(100, 200) += no +>> Byte(7).is_between(1, 7) += yes + +``` +## Byte.parse + +```tomo +Byte.parse : func(text: Text -> Byte?) +``` + +Parse a byte literal from text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to parse. | + +**Return:** The byte parsed from the text, if successful, otherwise `none`. + + +**Example:** +```tomo +>> Byte.parse("5") += Byte(5)? +>> Byte.parse("asdf") += none + +``` +## Byte.to + +```tomo +Byte.to : func(first: Byte, last: Byte, step: Byte? = none -> func(->Byte?)) +``` + +Returns an iterator function that iterates over the range of bytes specified. + +Argument | Type | Description | Default +---------|------|-------------|--------- +first | `Byte` | The starting value of the range. | +last | `Byte` | The ending value of the range. | +step | `Byte?` | An optional step size to use. If unspecified or `none`, the step will be inferred to be `+1` if `last >= first`, otherwise `-1`. | **Default:** `none` + +**Return:** An iterator function that returns each byte in the given range (inclusive). + + +**Example:** +```tomo +>> Byte(2).to(5) += func(->Byte?) +>> [x for x in Byte(2).to(5)] += [Byte(2), Byte(3), Byte(4), Byte(5)] +>> [x for x in Byte(5).to(2)] += [Byte(5), Byte(4), Byte(3), Byte(2)] + +>> [x for x in Byte(2).to(5, step=2)] += [Byte(2), Byte(4)] + +``` diff --git a/api/bytes.yaml b/api/bytes.yaml new file mode 100644 index 00000000..01f27fc3 --- /dev/null +++ b/api/bytes.yaml @@ -0,0 +1,104 @@ +Byte.hex: + description: > + Convert a byte to a hexidecimal text representation. + return: + type: 'Text' + description: > + The byte as a hexidecimal text. + args: + byte: + type: 'Byte' + description: > + The byte to convert to hex. + uppercase: + type: 'Bool' + default: 'yes' + description: > + Whether or not to use uppercase hexidecimal letters. + prefix: + type: 'Bool' + default: 'no' + description: > + Whether or not to prepend a `0x` prefix. + example: | + >> Byte(18).hex() + = "0x12" + +Byte.is_between: + description: > + Determines if an integer is between two numbers (inclusive). + return: + type: 'Bool' + description: > + `yes` if `low <= x and x <= high`, otherwise `no` + args: + x: + type: 'Byte' + description: > + The integer to be checked. + low: + type: 'Byte' + description: > + The lower bound to check (inclusive). + high: + type: 'Byte' + description: > + The upper bound to check (inclusive). + example: | + >> Byte(7).is_between(1, 10) + = yes + >> Byte(7).is_between(100, 200) + = no + >> Byte(7).is_between(1, 7) + = yes + +Byte.parse: + description: > + Parse a byte literal from text. + return: + type: 'Byte?' + description: > + The byte parsed from the text, if successful, otherwise `none`. + args: + text: + type: 'Text' + description: > + The text to parse. + example: | + >> Byte.parse("5") + = Byte(5)? + >> Byte.parse("asdf") + = none + +Byte.to: + description: > + Returns an iterator function that iterates over the range of bytes specified. + return: + type: 'func(->Byte?)' + description: > + An iterator function that returns each byte in the given range (inclusive). + args: + first: + type: 'Byte' + description: > + The starting value of the range. + last: + type: 'Byte' + description: > + The ending value of the range. + step: + type: 'Byte?' + default: 'none' + description: > + An optional step size to use. If unspecified or `none`, the step will be inferred to be `+1` if `last >= first`, otherwise `-1`. + example: | + >> Byte(2).to(5) + = func(->Byte?) + >> [x for x in Byte(2).to(5)] + = [Byte(2), Byte(3), Byte(4), Byte(5)] + >> [x for x in Byte(5).to(2)] + = [Byte(5), Byte(4), Byte(3), Byte(2)] + + >> [x for x in Byte(2).to(5, step=2)] + = [Byte(2), Byte(4)] + diff --git a/api/integers.md b/api/integers.md new file mode 100644 index 00000000..079bf266 --- /dev/null +++ b/api/integers.md @@ -0,0 +1,370 @@ +% API + +# Builtins + +# Int +## Int.abs + +```tomo +Int.abs : func(x: Int -> Int) +``` + +Calculates the absolute value of an integer. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Int` | The integer whose absolute value is to be calculated. | + +**Return:** The absolute value of `x`. + + +**Example:** +```tomo +>> (-10).abs() += 10 + +``` +## Int.choose + +```tomo +Int.choose : func(n: Int, k: Int -> Int) +``` + +Computes the binomial coefficient of the given numbers (the equivalent of `n` choose `k` in combinatorics). This is equal to `n.factorial()/(k.factorial() * (n-k).factorial())`. + +Argument | Type | Description | Default +---------|------|-------------|--------- +n | `Int` | The number of things to choose from. | +k | `Int` | The number of things to be chosen. | + +**Return:** The binomial coefficient, equivalent to the number of ways to uniquely choose `k` objects from among `n` objects, ignoring order. + + +**Example:** +```tomo +>> (4).choose(2) += 6 + +``` +## Int.clamped + +```tomo +Int.clamped : func(x: Int, low: Int, high: Int -> Int) +``` + +Returns the given number clamped between two values so that it is within that range. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Int` | The integer to clamp. | +low | `Int` | The lowest value the result can take. | +high | `Int` | The highest value the result can take. | + +**Return:** The first argument clamped between the other two arguments. + + +**Example:** +```tomo +>> (2).clamped(5, 10) += 5 + +``` +## Int.factorial + +```tomo +Int.factorial : func(n: Int -> Text) +``` + +Computes the factorial of an integer. + +Argument | Type | Description | Default +---------|------|-------------|--------- +n | `Int` | The integer to compute the factorial of. | + +**Return:** The factorial of the given integer. + + +**Example:** +```tomo +>> (10).factorial() += 3628800 + +``` +## Int.format + +```tomo +Int.format : func(i: Int, digits: Int = 0 -> Text) +``` + +Formats an integer as a string with a specified number of digits. + +Argument | Type | Description | Default +---------|------|-------------|--------- +i | `Int` | The integer to be formatted. | +digits | `Int` | The minimum number of digits to which the integer should be padded. | **Default:** `0` + +**Return:** A string representation of the integer, padded to the specified number of digits. + + +**Example:** +```tomo +>> (42).format(digits=5) += "00042" + +``` +## Int.hex + +```tomo +Int.hex : func(i: Int, digits: Int = 0, uppercase: Bool = yes, prefix: Bool = yes -> Text) +``` + +Converts an integer to its hexadecimal representation. + +Argument | Type | Description | Default +---------|------|-------------|--------- +i | `Int` | The integer to be converted. | +digits | `Int` | The minimum number of digits in the output string. | **Default:** `0` +uppercase | `Bool` | Whether to use uppercase letters for hexadecimal digits. | **Default:** `yes` +prefix | `Bool` | Whether to include a "0x" prefix. | **Default:** `yes` + +**Return:** The hexadecimal string representation of the integer. + + +**Example:** +```tomo +>> (255).hex(digits=4, uppercase=yes, prefix=yes) += "0x00FF" + +``` +## Int.is_between + +```tomo +Int.is_between : func(x: Int, low: Int, high: Int -> Bool) +``` + +Determines if an integer is between two numbers (inclusive). + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Int` | The integer to be checked. | +low | `Int` | The lower bound to check (inclusive). | +high | `Int` | The upper bound to check (inclusive). | + +**Return:** `yes` if `low <= x and x <= high`, otherwise `no` + + +**Example:** +```tomo +>> (7).is_between(1, 10) += yes +>> (7).is_between(100, 200) += no +>> (7).is_between(1, 7) += yes + +``` +## Int.is_prime + +```tomo +Int.is_prime : func(x: Int, reps: Int = 50 -> Bool) +``` + +Determines if an integer is a prime number. + +This function is _probabilistic_. With the default arguments, the chances of getting an incorrect answer are astronomically small (on the order of 10^(-30)). See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp) for more details. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Int` | The integer to be checked. | +reps | `Int` | The number of repetitions for primality tests. | **Default:** `50` + +**Return:** `yes` if `x` is a prime number, `no` otherwise. + + +**Example:** +```tomo +>> (7).is_prime() += yes +>> (6).is_prime() += no + +``` +## Int.next_prime + +```tomo +Int.next_prime : func(x: Int -> Int) +``` + +Finds the next prime number greater than the given integer. + +This function is _probabilistic_, but the chances of getting an incorrect answer are astronomically small (on the order of 10^(-30)). See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp) for more details. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Int` | The integer after which to find the next prime. | + +**Return:** The next prime number greater than `x`. + + +**Example:** +```tomo +>> (11).next_prime() += 13 + +``` +## Int.octal + +```tomo +Int.octal : func(i: Int, digits: Int = 0, prefix: Bool = yes -> Text) +``` + +Converts an integer to its octal representation. + +Argument | Type | Description | Default +---------|------|-------------|--------- +i | `Int` | The integer to be converted. | +digits | `Int` | The minimum number of digits in the output string. | **Default:** `0` +prefix | `Bool` | Whether to include a "0o" prefix. | **Default:** `yes` + +**Return:** The octal string representation of the integer. + + +**Example:** +```tomo +>> (64).octal(digits=4, prefix=yes) += "0o0100" + +``` +## Int.onward + +```tomo +Int.onward : func(first: Int, step: Int = 1 -> Text) +``` + +Return an iterator that counts infinitely from the starting integer (with an optional step size). + +Argument | Type | Description | Default +---------|------|-------------|--------- +first | `Int` | The starting integer. | +step | `Int` | The increment step size. | **Default:** `1` + +**Return:** An iterator function that counts onward from the starting integer. + + +**Example:** +```tomo +nums : &[Int] = &[] +for i in (5).onward() +nums.insert(i) +stop if i == 10 +>> nums[] += [5, 6, 7, 8, 9, 10] + +``` +## Int.parse + +```tomo +Int.parse : func(text: Text -> Int?) +``` + +Converts a text representation of an integer into an integer. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text containing the integer. | + +**Return:** The integer represented by the text. If the given text contains a value outside of the representable range or if the entire text can't be parsed as an integer, `none` will be returned. + + +**Example:** +```tomo +>> Int.parse("123") += 123 : Int? +>> Int.parse("0xFF") += 255 : Int? + +# Can't parse: +>> Int.parse("asdf") += none : Int? + +# Outside valid range: +>> Int8.parse("9999999") += none : Int8? + +``` +## Int.prev_prime + +```tomo +Int.prev_prime : func(x: Int -> Int?) +``` + +Finds the previous prime number less than the given integer. If there is no previous prime number (i.e. if a number less than `2` is provided), then the function will create a runtime error. + +This function is _probabilistic_, but the chances of getting an incorrect answer are astronomically small (on the order of 10^(-30)). See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp) for more details. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Int` | The integer before which to find the previous prime. | + +**Return:** The previous prime number less than `x`, or `none` if `x` is less than 2. + + +**Example:** +```tomo +>> (11).prev_prime() += 7 + +``` +## Int.sqrt + +```tomo +Int.sqrt : func(x: Int -> Int) +``` + +Calculates the nearest square root of an integer. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Int` | The integer whose square root is to be calculated. | + +**Return:** The integer part of the square root of `x`. + + +**Example:** +```tomo +>> (16).sqrt() += 4 +>> (17).sqrt() += 4 + +``` +## Int.to + +```tomo +Int.to : func(first: Int, last: Int, step: Int? = none -> func(->Int?)) +``` + +Returns an iterator function that iterates over the range of numbers specified. + +Argument | Type | Description | Default +---------|------|-------------|--------- +first | `Int` | The starting value of the range. | +last | `Int` | The ending value of the range. | +step | `Int?` | An optional step size to use. If unspecified or `none`, the step will be inferred to be `+1` if `last >= first`, otherwise `-1`. | **Default:** `none` + +**Return:** An iterator function that returns each integer in the given range (inclusive). + + +**Example:** +```tomo +>> (2).to(5) += func(->Int?) +>> [x for x in (2).to(5)] += [2, 3, 4, 5] +>> [x for x in (5).to(2)] += [5, 4, 3, 2] + +>> [x for x in (2).to(5, step=2)] += [2, 4] + +``` diff --git a/api/integers.yaml b/api/integers.yaml new file mode 100644 index 00000000..e13246e8 --- /dev/null +++ b/api/integers.yaml @@ -0,0 +1,362 @@ +Int.abs: + description: > + Calculates the absolute value of an integer. + return: + type: 'Int' + description: > + The absolute value of `x`. + args: + x: + type: 'Int' + description: > + The integer whose absolute value is to be calculated. + example: | + >> (-10).abs() + = 10 + +Int.choose: + description: > + Computes the binomial coefficient of the given numbers (the equivalent of `n` + choose `k` in combinatorics). This is equal to `n.factorial()/(k.factorial() * + (n-k).factorial())`. + return: + type: 'Int' + description: > + The binomial coefficient, equivalent to the number of ways to uniquely choose + `k` objects from among `n` objects, ignoring order. + args: + n: + type: 'Int' + description: > + The number of things to choose from. + k: + type: 'Int' + description: > + The number of things to be chosen. + example: | + >> (4).choose(2) + = 6 + +Int.clamped: + description: > + Returns the given number clamped between two values so that it is within + that range. + return: + type: 'Int' + description: > + The first argument clamped between the other two arguments. + args: + x: + type: 'Int' + description: > + The integer to clamp. + low: + type: 'Int' + description: > + The lowest value the result can take. + high: + type: 'Int' + description: > + The highest value the result can take. + example: | + >> (2).clamped(5, 10) + = 5 + +Int.factorial: + description: > + Computes the factorial of an integer. + return: + type: 'Text' + description: > + The factorial of the given integer. + args: + n: + type: 'Int' + description: > + The integer to compute the factorial of. + example: | + >> (10).factorial() + = 3628800 + +Int.format: + description: > + Formats an integer as a string with a specified number of digits. + return: + type: 'Text' + description: > + A string representation of the integer, padded to the specified number of digits. + args: + i: + type: 'Int' + description: > + The integer to be formatted. + digits: + type: 'Int' + default: '0' + description: > + The minimum number of digits to which the integer should be padded. + example: | + >> (42).format(digits=5) + = "00042" + +Int.hex: + description: > + Converts an integer to its hexadecimal representation. + return: + type: 'Text' + description: > + The hexadecimal string representation of the integer. + args: + i: + type: 'Int' + description: > + The integer to be converted. + digits: + type: 'Int' + default: '0' + description: > + The minimum number of digits in the output string. + uppercase: + type: 'Bool' + default: 'yes' + description: > + Whether to use uppercase letters for hexadecimal digits. + prefix: + type: 'Bool' + default: 'yes' + description: > + Whether to include a "0x" prefix. + example: | + >> (255).hex(digits=4, uppercase=yes, prefix=yes) + = "0x00FF" + +Int.is_between: + description: > + Determines if an integer is between two numbers (inclusive). + return: + type: 'Bool' + description: > + `yes` if `low <= x and x <= high`, otherwise `no` + args: + x: + type: 'Int' + description: > + The integer to be checked. + low: + type: 'Int' + description: > + The lower bound to check (inclusive). + high: + type: 'Int' + description: > + The upper bound to check (inclusive). + example: | + >> (7).is_between(1, 10) + = yes + >> (7).is_between(100, 200) + = no + >> (7).is_between(1, 7) + = yes + +Int.is_prime: + description: > + Determines if an integer is a prime number. + note: > + This function is _probabilistic_. With the default arguments, the chances of + getting an incorrect answer are astronomically small (on the order of 10^(-30)). + See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp) + for more details. + return: + type: 'Bool' + description: > + `yes` if `x` is a prime number, `no` otherwise. + args: + x: + type: 'Int' + description: > + The integer to be checked. + reps: + type: 'Int' + default: '50' + description: > + The number of repetitions for primality tests. + example: | + >> (7).is_prime() + = yes + >> (6).is_prime() + = no + +Int.next_prime: + description: > + Finds the next prime number greater than the given integer. + note: > + This function is _probabilistic_, but the chances of getting an incorrect + answer are astronomically small (on the order of 10^(-30)). + See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp) + for more details. + return: + type: 'Int' + description: > + The next prime number greater than `x`. + args: + x: + type: 'Int' + description: > + The integer after which to find the next prime. + example: | + >> (11).next_prime() + = 13 + +Int.octal: + description: > + Converts an integer to its octal representation. + return: + type: 'Text' + description: > + The octal string representation of the integer. + args: + i: + type: 'Int' + description: > + The integer to be converted. + digits: + type: 'Int' + default: '0' + description: > + The minimum number of digits in the output string. + prefix: + type: 'Bool' + default: 'yes' + description: > + Whether to include a "0o" prefix. + example: | + >> (64).octal(digits=4, prefix=yes) + = "0o0100" + +Int.onward: + description: > + Return an iterator that counts infinitely from the starting integer (with an + optional step size). + return: + type: 'Text' + description: > + An iterator function that counts onward from the starting integer. + args: + first: + type: 'Int' + description: > + The starting integer. + step: + type: 'Int' + default: '1' + description: > + The increment step size. + example: | + nums : &[Int] = &[] + for i in (5).onward() + nums.insert(i) + stop if i == 10 + >> nums[] + = [5, 6, 7, 8, 9, 10] + +Int.parse: + description: > + Converts a text representation of an integer into an integer. + return: + type: 'Int?' + description: > + The integer represented by the text. If the given text contains a value outside + of the representable range or if the entire text can't be parsed as an integer, + `none` will be returned. + args: + text: + type: 'Text' + description: > + The text containing the integer. + example: | + >> Int.parse("123") + = 123 : Int? + >> Int.parse("0xFF") + = 255 : Int? + + # Can't parse: + >> Int.parse("asdf") + = none : Int? + + # Outside valid range: + >> Int8.parse("9999999") + = none : Int8? + +Int.prev_prime: + description: > + Finds the previous prime number less than the given integer. + If there is no previous prime number (i.e. if a number less than `2` is + provided), then the function will create a runtime error. + note: > + This function is _probabilistic_, but the chances of getting an incorrect + answer are astronomically small (on the order of 10^(-30)). + See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp) + for more details. + return: + type: 'Int?' + description: > + The previous prime number less than `x`, or `none` if `x` is less than 2. + args: + x: + type: 'Int' + description: > + The integer before which to find the previous prime. + example: | + >> (11).prev_prime() + = 7 + +Int.sqrt: + description: > + Calculates the nearest square root of an integer. + return: + type: 'Int' + description: > + The integer part of the square root of `x`. + args: + x: + type: 'Int' + description: > + The integer whose square root is to be calculated. + example: | + >> (16).sqrt() + = 4 + >> (17).sqrt() + = 4 + +Int.to: + description: > + Returns an iterator function that iterates over the range of numbers specified. + return: + type: 'func(->Int?)' + description: > + An iterator function that returns each integer in the given range (inclusive). + args: + first: + type: 'Int' + description: > + The starting value of the range. + last: + type: 'Int' + description: > + The ending value of the range. + step: + type: 'Int?' + default: 'none' + description: > + An optional step size to use. If unspecified or `none`, the step will be inferred to be `+1` if `last >= first`, otherwise `-1`. + example: | + >> (2).to(5) + = func(->Int?) + >> [x for x in (2).to(5)] + = [2, 3, 4, 5] + >> [x for x in (5).to(2)] + = [5, 4, 3, 2] + + >> [x for x in (2).to(5, step=2)] + = [2, 4] + diff --git a/api/lists.md b/api/lists.md new file mode 100644 index 00000000..4e27f844 --- /dev/null +++ b/api/lists.md @@ -0,0 +1,651 @@ +% API + +# Builtins + +# List +## List.binary_search + +```tomo +List.binary_search : func(list: [T], by: func(x,y:&T->Int32) = T.compare -> Int) +``` + +Performs a binary search on a sorted list. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The sorted list to search. | +by | `func(x,y:&T->Int32)` | The comparison function used to determine order. If not specified, the default comparison function for the item type will be used. | **Default:** `T.compare` + +**Return:** Assuming the input list is sorted according to the given comparison function, return the index where the given item would be inserted to maintain the sorted order. That is, if the item is found, return its index, otherwise return the place where it would be found if it were inserted and the list were sorted. + + +**Example:** +```tomo +>> [1, 3, 5, 7, 9].binary_search(5) += 3 + +>> [1, 3, 5, 7, 9].binary_search(-999) += 1 + +>> [1, 3, 5, 7, 9].binary_search(999) += 6 + +``` +## List.by + +```tomo +List.by : func(list: [T], step: Int -> [T]) +``` + +Creates a new list with elements spaced by the specified step value. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The original list. | +step | `Int` | The step value for selecting elements. | + +**Return:** A new list with every `step`-th element from the original list. + + +**Example:** +```tomo +>> [1, 2, 3, 4, 5, 6].by(2) += [1, 3, 5] + +``` +## List.clear + +```tomo +List.clear : func(list: @[T] -> Void) +``` + +Clears all elements from the list. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `@[T]` | The mutable reference to the list to be cleared. | + +**Return:** Nothing. + + +**Example:** +```tomo +>> my_list.clear() + +``` +## List.counts + +```tomo +List.counts : func(list: [T] -> {T=Int}) +``` + +Counts the occurrences of each element in the list. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The list to count elements in. | + +**Return:** A table mapping each element to its count. + + +**Example:** +```tomo +>> [10, 20, 30, 30, 30].counts() += {10=1, 20=1, 30=3} + +``` +## List.find + +```tomo +List.find : func(list: [T], target: T -> Int?) +``` + +Finds the index of the first occurrence of an element (if any). + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The list to search through. | +target | `T` | The item to search for. | + +**Return:** The index of the first occurrence or `!Int` if not found. + + +**Example:** +```tomo +>> [10, 20, 30, 40, 50].find(20) += 2 : Int? + +>> [10, 20, 30, 40, 50].find(9999) += none : Int? + +``` +## List.first + +```tomo +List.first : func(list: [T], predicate: func(item:&T -> Bool) -> Int) +``` + +Find the index of the first item that matches a predicate function (if any). + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The list to search through. | +predicate | `func(item:&T -> Bool)` | A function that returns `yes` if the item should be returned or `no` if it should not. | + +**Return:** Returns the index of the first item where the predicate is true or `!Int` if no item matches. + + +**Example:** +```tomo +>> [4, 5, 6].find(func(i:&Int): i.is_prime()) += 5 : Int? +>> [4, 6, 8].find(func(i:&Int): i.is_prime()) += none : Int? + +``` +## List.from + +```tomo +List.from : func(list: [T], first: Int -> [T]) +``` + +Returns a slice of the list starting from a specified index. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The original list. | +first | `Int` | The index to start from. | + +**Return:** A new list starting from the specified index. + + +**Example:** +```tomo +>> [10, 20, 30, 40, 50].from(3) += [30, 40, 50] + +``` +## List.has + +```tomo +List.has : func(list: [T], target: T -> Bool) +``` + +Checks if the list has an element. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The list to check. | +target | `T` | The element to check for. | + +**Return:** `yes` if the list has the element, `no` otherwise. + + +**Example:** +```tomo +>> [10, 20, 30].has(20) += yes + +``` +## List.heap_pop + +```tomo +List.heap_pop : func(list: @[T], by: func(x,y:&T->Int32) = T.compare -> T?) +``` + +Removes and returns the top element of a heap or `none` if the list is empty. By default, this is the *minimum* value in the heap. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `@[T]` | The mutable reference to the heap. | +by | `func(x,y:&T->Int32)` | The comparison function used to determine order. If not specified, the default comparison function for the item type will be used. | **Default:** `T.compare` + +**Return:** The removed top element of the heap or `none` if the list is empty. + + +**Example:** +```tomo +>> my_heap := [30, 10, 20] +>> my_heap.heapify() +>> my_heap.heap_pop() += 10 + +``` +## List.heap_push + +```tomo +List.heap_push : func(list: @[T], item: T, by = T.compare -> Void) +``` + +Adds an element to the heap and maintains the heap property. By default, this is a *minimum* heap. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `@[T]` | The mutable reference to the heap. | +item | `T` | The item to be added. | +by | `` | The comparison function used to determine order. If not specified, the default comparison function for the item type will be used. | **Default:** `T.compare` + +**Return:** Nothing. + + +**Example:** +```tomo +>> my_heap.heap_push(10) + +``` +## List.heapify + +```tomo +List.heapify : func(list: @[T], by: func(x,y:&T->Int32) = T.compare -> Void) +``` + +Converts a list into a heap. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `@[T]` | The mutable reference to the list to be heapified. | +by | `func(x,y:&T->Int32)` | The comparison function used to determine order. If not specified, the default comparison function for the item type will be used. | **Default:** `T.compare` + +**Return:** Nothing. + + +**Example:** +```tomo +>> my_heap := [30, 10, 20] +>> my_heap.heapify() + +``` +## List.insert + +```tomo +List.insert : func(list: @[T], item: T, at: Int = 0 -> Void) +``` + +Inserts an element at a specified position in the list. + +Since indices are 1-indexed and negative indices mean "starting from the back", an index of `0` means "after the last item". + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `@[T]` | The mutable reference to the list. | +item | `T` | The item to be inserted. | +at | `Int` | The index at which to insert the item. | **Default:** `0` + +**Return:** Nothing. + + +**Example:** +```tomo +>> list := [10, 20] +>> list.insert(30) +>> list += [10, 20, 30] + +>> list.insert(999, at=2) +>> list += [10, 999, 20, 30] + +``` +## List.insert_all + +```tomo +List.insert_all : func(list: @[T], items: [T], at: Int = 0 -> Void) +``` + +Inserts a list of items at a specified position in the list. + +Since indices are 1-indexed and negative indices mean "starting from the back", an index of `0` means "after the last item". + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `@[T]` | The mutable reference to the list. | +items | `[T]` | The items to be inserted. | +at | `Int` | The index at which to insert the item. | **Default:** `0` + +**Return:** Nothing. + + +**Example:** +```tomo +list := [10, 20] +list.insert_all([30, 40]) +>> list += [10, 20, 30, 40] + +list.insert_all([99, 100], at=2) +>> list += [10, 99, 100, 20, 30, 40] + +``` +## List.pop + +```tomo +List.pop : func(list: &[T], index: Int = -1 -> T?) +``` + +Removes and returns an item from the list. If the given index is present in the list, the item at that index will be removed and the list will become one element shorter. + +Since negative indices are counted from the back, the default behavior is to pop the last value. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `&[T]` | The list to remove an item from. | +index | `Int` | The index from which to remove the item. | **Default:** `-1` + +**Return:** `none` if the list is empty or the given index does not exist in the list, otherwise the item at the given index. + + +**Example:** +```tomo +>> list := [10, 20, 30, 40] + +>> list.pop() += 40 +>> list += &[10, 20, 30] + +>> list.pop(index=2) += 20 +>> list += &[10, 30] + +``` +## List.random + +```tomo +List.random : func(list: [T], random: func(min,max:Int64->Int64)? = none -> T) +``` + +Selects a random element from the list. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The list from which to select a random element. | +random | `func(min,max:Int64->Int64)?` | If provided, this function will be used to get a random index in the list. Returned values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number generation) | **Default:** `none` + +**Return:** A random element from the list. + + +**Example:** +```tomo +>> [10, 20, 30].random() += 20 + +``` +## List.remove_at + +```tomo +List.remove_at : func(list: @[T], at: Int = -1, count: Int = 1 -> Void) +``` + +Removes elements from the list starting at a specified index. + +Since negative indices are counted from the back, the default behavior is to remove the last item. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `@[T]` | The mutable reference to the list. | +at | `Int` | The index at which to start removing elements. | **Default:** `-1` +count | `Int` | The number of elements to remove. | **Default:** `1` + +**Return:** Nothing. + + +**Example:** +```tomo +list := [10, 20, 30, 40, 50] +list.remove_at(2) +>> list += [10, 30, 40, 50] + +list.remove_at(2, count=2) +>> list += [10, 50] + +``` +## List.remove_item + +```tomo +List.remove_item : func(list: @[T], item: T, max_count: Int = -1 -> Void) +``` + +Removes all occurrences of a specified item from the list. + +A negative `max_count` means "remove all occurrences". + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `@[T]` | The mutable reference to the list. | +item | `T` | The item to be removed. | +max_count | `Int` | The maximum number of occurrences to remove. | **Default:** `-1` + +**Return:** Nothing. + + +**Example:** +```tomo +list := [10, 20, 10, 20, 30] +list.remove_item(10) +>> list += [20, 20, 30] + +list.remove_item(20, max_count=1) +>> list += [20, 30] + +``` +## List.reversed + +```tomo +List.reversed : func(list: [T] -> [T]) +``` + +Returns a reversed slice of the list. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The list to be reversed. | + +**Return:** A slice of the list with elements in reverse order. + + +**Example:** +```tomo +>> [10, 20, 30].reversed() += [30, 20, 10] + +``` +## List.sample + +```tomo +List.sample : func(list: [T], count: Int, weights: [Num]? = ![Num], random: func(->Num)? = none -> [T]) +``` + +Selects a sample of elements from the list, optionally with weighted probabilities. + +Errors will be raised if any of the following conditions occurs: - The given list has no elements and `count >= 1` - `count < 0` (negative count) - The number of weights provided doesn't match the length of the list. - Any weight in the weights list is negative, infinite, or `NaN` - The sum of the given weights is zero (zero probability for every element). + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The list to sample from. | +count | `Int` | The number of elements to sample. | +weights | `[Num]?` | The probability weights for each element in the list. These values do not need to add up to any particular number, they are relative weights. If no weights are given, elements will be sampled with uniform probability. | **Default:** `![Num]` +random | `func(->Num)?` | If provided, this function will be used to get random values for sampling the list. The provided function should return random numbers between `0.0` (inclusive) and `1.0` (exclusive). (Used for deterministic pseudorandom number generation) | **Default:** `none` + +**Return:** A list of sampled elements from the list. + + +**Example:** +```tomo +>> [10, 20, 30].sample(2, weights=[90%, 5%, 5%]) += [10, 10] + +``` +## List.shuffle + +```tomo +List.shuffle : func(list: @[T], random: func(min,max:Int64->Int64)? = none -> Void) +``` + +Shuffles the elements of the list in place. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `@[T]` | The mutable reference to the list to be shuffled. | +random | `func(min,max:Int64->Int64)?` | If provided, this function will be used to get a random index in the list. Returned values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number generation) | **Default:** `none` + +**Return:** Nothing. + + +**Example:** +```tomo +>> list.shuffle() + +``` +## List.shuffled + +```tomo +List.shuffled : func(list: [T], random: func(min,max:Int64->Int64)? = none -> [T]) +``` + +Creates a new list with elements shuffled. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The list to be shuffled. | +random | `func(min,max:Int64->Int64)?` | If provided, this function will be used to get a random index in the list. Returned values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number generation) | **Default:** `none` + +**Return:** A new list with shuffled elements. + + +**Example:** +```tomo +>> [10, 20, 30, 40].shuffled() += [40, 10, 30, 20] + +``` +## List.slice + +```tomo +List.slice : func(list: [T], from: Int, to: Int -> [T]) +``` + +Returns a slice of the list spanning the given indices (inclusive). + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The original list. | +from | `Int` | The first index to include. | +to | `Int` | The last index to include. | + +**Return:** A new list spanning the given indices. Note: negative indices are counted from the back of the list, so `-1` refers to the last element, `-2` the second-to-last, and so on. + + +**Example:** +```tomo +>> [10, 20, 30, 40, 50].slice(2, 4) += [20, 30, 40] + +>> [10, 20, 30, 40, 50].slice(-3, -2) += [30, 40] + +``` +## List.sort + +```tomo +List.sort : func(list: @[T], by = T.compare -> Void) +``` + +Sorts the elements of the list in place in ascending order (small to large). + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `@[T]` | The mutable reference to the list to be sorted. | +by | `` | The comparison function used to determine order. If not specified, the default comparison function for the item type will be used. | **Default:** `T.compare` + +**Return:** Nothing. + + +**Example:** +```tomo +list := [40, 10, -30, 20] +list.sort() +>> list += [-30, 10, 20, 40] + +list.sort(func(a,b:&Int): a.abs() <> b.abs()) +>> list += [10, 20, -30, 40] + +``` +## List.sorted + +```tomo +List.sorted : func(list: [T], by = T.compare -> [T]) +``` + +Creates a new list with elements sorted. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The list to be sorted. | +by | `` | The comparison function used to determine order. If not specified, the default comparison function for the item type will be used. | **Default:** `T.compare` + +**Return:** A new list with sorted elements. + + +**Example:** +```tomo +>> [40, 10, -30, 20].sorted() += [-30, 10, 20, 40] + +>> [40, 10, -30, 20].sorted(func(a,b:&Int): a.abs() <> b.abs()) += [10, 20, -30, 40] + +``` +## List.to + +```tomo +List.to : func(list: [T], last: Int -> [T]) +``` + +Returns a slice of the list from the start of the original list up to a specified index (inclusive). + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The original list. | +last | `Int` | The index up to which elements should be included. | + +**Return:** A new list containing elements from the start up to the specified index. + + +**Example:** +```tomo +>> [10, 20, 30, 40, 50].to(3) += [10, 20, 30] + +>> [10, 20, 30, 40, 50].to(-2) += [10, 20, 30, 40] + +``` +## List.unique + +```tomo +List.unique : func(list: [T] -> |T|) +``` + +Returns a Set that contains the unique elements of the list. + +Argument | Type | Description | Default +---------|------|-------------|--------- +list | `[T]` | The list to process. | + +**Return:** A set containing only unique elements from the list. + + +**Example:** +```tomo +>> [10, 20, 10, 10, 30].unique() += {10, 20, 30} + +``` diff --git a/api/lists.yaml b/api/lists.yaml new file mode 100644 index 00000000..c746cf57 --- /dev/null +++ b/api/lists.yaml @@ -0,0 +1,660 @@ +List.binary_search: + description: > + Performs a binary search on a sorted list. + return: + type: 'Int' + description: > + Assuming the input list is sorted according to the given comparison function, + return the index where the given item would be inserted to maintain the sorted + order. That is, if the item is found, return its index, otherwise return the + place where it would be found if it were inserted and the list were sorted. + args: + list: + type: '[T]' + description: > + The sorted list to search. + by: + type: 'func(x,y:&T->Int32)' + default: 'T.compare' + description: > + The comparison function used to determine order. If not specified, the + default comparison function for the item type will be used. + example: | + >> [1, 3, 5, 7, 9].binary_search(5) + = 3 + + >> [1, 3, 5, 7, 9].binary_search(-999) + = 1 + + >> [1, 3, 5, 7, 9].binary_search(999) + = 6 + +List.by: + description: > + Creates a new list with elements spaced by the specified step value. + return: + type: '[T]' + description: > + A new list with every `step`-th element from the original list. + args: + list: + type: '[T]' + description: > + The original list. + step: + type: 'Int' + description: > + The step value for selecting elements. + example: | + >> [1, 2, 3, 4, 5, 6].by(2) + = [1, 3, 5] + +List.clear: + description: > + Clears all elements from the list. + return: + type: 'Void' + description: > + Nothing. + args: + list: + type: '@[T]' + description: > + The mutable reference to the list to be cleared. + example: | + >> my_list.clear() + +List.counts: + description: > + Counts the occurrences of each element in the list. + return: + type: '{T=Int}' + description: > + A table mapping each element to its count. + args: + list: + type: '[T]' + description: > + The list to count elements in. + example: | + >> [10, 20, 30, 30, 30].counts() + = {10=1, 20=1, 30=3} + +List.find: + description: > + Finds the index of the first occurrence of an element (if any). + return: + type: 'Int?' + description: > + The index of the first occurrence or `!Int` if not found. + args: + list: + type: '[T]' + description: > + The list to search through. + target: + type: 'T' + description: > + The item to search for. + example: | + >> [10, 20, 30, 40, 50].find(20) + = 2 : Int? + + >> [10, 20, 30, 40, 50].find(9999) + = none : Int? + +List.first: + description: > + Find the index of the first item that matches a predicate function (if any). + return: + type: 'Int' + description: > + Returns the index of the first item where the predicate is true or `!Int` if no + item matches. + args: + list: + type: '[T]' + description: > + The list to search through. + predicate: + type: 'func(item:&T -> Bool)' + description: > + A function that returns `yes` if the item should be returned or + `no` if it should not. + example: | + >> [4, 5, 6].find(func(i:&Int): i.is_prime()) + = 5 : Int? + >> [4, 6, 8].find(func(i:&Int): i.is_prime()) + = none : Int? + +List.from: + description: > + Returns a slice of the list starting from a specified index. + return: + type: '[T]' + description: > + A new list starting from the specified index. + args: + list: + type: '[T]' + description: > + The original list. + first: + type: 'Int' + description: > + The index to start from. + example: | + >> [10, 20, 30, 40, 50].from(3) + = [30, 40, 50] + +List.has: + description: > + Checks if the list has an element. + return: + type: 'Bool' + description: > + `yes` if the list has the element, `no` otherwise. + args: + list: + type: '[T]' + description: > + The list to check. + target: + type: 'T' + description: > + The element to check for. + example: | + >> [10, 20, 30].has(20) + = yes + +List.heap_pop: + description: > + Removes and returns the top element of a heap or `none` if the list is empty. + By default, this is the *minimum* value in the heap. + return: + type: 'T?' + description: > + The removed top element of the heap or `none` if the list is empty. + args: + list: + type: '@[T]' + description: > + The mutable reference to the heap. + by: + type: 'func(x,y:&T->Int32)' + default: 'T.compare' + description: > + The comparison function used to determine order. If not specified, the + default comparison function for the item type will be used. + example: | + >> my_heap := [30, 10, 20] + >> my_heap.heapify() + >> my_heap.heap_pop() + = 10 + +List.heap_push: + description: > + Adds an element to the heap and maintains the heap property. By default, this + is a *minimum* heap. + return: + type: 'Void' + description: > + Nothing. + args: + list: + type: '@[T]' + description: > + The mutable reference to the heap. + item: + type: 'T' + description: > + The item to be added. + by: + default: 'T.compare' + description: > + The comparison function used to determine order. If not specified, the + default comparison function for the item type will be used. + example: | + >> my_heap.heap_push(10) + +List.heapify: + description: > + Converts a list into a heap. + return: + type: 'Void' + description: > + Nothing. + args: + list: + type: '@[T]' + description: > + The mutable reference to the list to be heapified. + by: + type: 'func(x,y:&T->Int32)' + default: 'T.compare' + description: > + The comparison function used to determine order. If not specified, the + default comparison function for the item type will be used. + example: | + >> my_heap := [30, 10, 20] + >> my_heap.heapify() + +List.insert: + description: > + Inserts an element at a specified position in the list. + return: + type: 'Void' + description: > + Nothing. + args: + list: + type: '@[T]' + description: > + The mutable reference to the list. + item: + type: 'T' + description: > + The item to be inserted. + at: + type: 'Int' + default: '0' + description: > + The index at which to insert the item. + note: > + Since indices are 1-indexed and negative indices mean "starting from the + back", an index of `0` means "after the last item". + example: | + >> list := [10, 20] + >> list.insert(30) + >> list + = [10, 20, 30] + + >> list.insert(999, at=2) + >> list + = [10, 999, 20, 30] + +List.insert_all: + description: > + Inserts a list of items at a specified position in the list. + return: + type: 'Void' + description: > + Nothing. + args: + list: + type: '@[T]' + description: > + The mutable reference to the list. + items: + type: '[T]' + description: > + The items to be inserted. + at: + type: 'Int' + default: '0' + description: > + The index at which to insert the item. + note: > + Since indices are 1-indexed and negative indices mean "starting from the + back", an index of `0` means "after the last item". + example: | + list := [10, 20] + list.insert_all([30, 40]) + >> list + = [10, 20, 30, 40] + + list.insert_all([99, 100], at=2) + >> list + = [10, 99, 100, 20, 30, 40] + +List.pop: + description: > + Removes and returns an item from the list. If the given index is present in + the list, the item at that index will be removed and the list will become one + element shorter. + return: + type: 'T?' + description: > + `none` if the list is empty or the given index does not exist in the list, + otherwise the item at the given index. + args: + list: + type: '&[T]' + description: > + The list to remove an item from. + index: + type: 'Int' + default: '-1' + description: > + The index from which to remove the item. + note: > + Since negative indices are counted from the back, the default behavior is + to pop the last value. + example: | + >> list := [10, 20, 30, 40] + + >> list.pop() + = 40 + >> list + = &[10, 20, 30] + + >> list.pop(index=2) + = 20 + >> list + = &[10, 30] + +List.random: + description: > + Selects a random element from the list. + return: + type: 'T' + description: > + A random element from the list. + args: + list: + type: '[T]' + description: > + The list from which to select a random element. + random: + type: 'func(min,max:Int64->Int64)?' + default: 'none' + description: > + If provided, this function will be used to get a random index in the list. Returned + values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number + generation) + example: | + >> [10, 20, 30].random() + = 20 + +List.remove_at: + description: > + Removes elements from the list starting at a specified index. + return: + type: 'Void' + description: > + Nothing. + args: + list: + type: '@[T]' + description: > + The mutable reference to the list. + at: + type: 'Int' + default: '-1' + description: > + The index at which to start removing elements. + count: + type: 'Int' + default: '1' + description: > + The number of elements to remove. + note: > + Since negative indices are counted from the back, the default behavior is + to remove the last item. + example: | + list := [10, 20, 30, 40, 50] + list.remove_at(2) + >> list + = [10, 30, 40, 50] + + list.remove_at(2, count=2) + >> list + = [10, 50] + +List.remove_item: + description: > + Removes all occurrences of a specified item from the list. + return: + type: 'Void' + description: > + Nothing. + args: + list: + type: '@[T]' + description: > + The mutable reference to the list. + item: + type: 'T' + description: > + The item to be removed. + max_count: + type: 'Int' + default: '-1' + description: > + The maximum number of occurrences to remove. + note: > + A negative `max_count` means "remove all occurrences". + example: | + list := [10, 20, 10, 20, 30] + list.remove_item(10) + >> list + = [20, 20, 30] + + list.remove_item(20, max_count=1) + >> list + = [20, 30] + +List.reversed: + description: > + Returns a reversed slice of the list. + return: + type: '[T]' + description: > + A slice of the list with elements in reverse order. + args: + list: + type: '[T]' + description: > + The list to be reversed. + example: | + >> [10, 20, 30].reversed() + = [30, 20, 10] + +List.sample: + description: > + Selects a sample of elements from the list, optionally with weighted + probabilities. + return: + type: '[T]' + description: > + A list of sampled elements from the list. + errors: > + Errors will be raised if any of the following conditions occurs: + - The given list has no elements and `count >= 1` + - `count < 0` (negative count) + - The number of weights provided doesn't match the length of the list. + - Any weight in the weights list is negative, infinite, or `NaN` + - The sum of the given weights is zero (zero probability for every element). + args: + list: + type: '[T]' + description: > + The list to sample from. + count: + type: 'Int' + description: > + The number of elements to sample. + weights: + type: '[Num]?' + default: '![Num]' + description: > + The probability weights for each element in the list. These + values do not need to add up to any particular number, they are relative + weights. If no weights are given, elements will be sampled with uniform + probability. + random: + type: 'func(->Num)?' + default: 'none' + description: > + If provided, this function will be used to get random values for + sampling the list. The provided function should return random numbers + between `0.0` (inclusive) and `1.0` (exclusive). (Used for deterministic + pseudorandom number generation) + example: | + >> [10, 20, 30].sample(2, weights=[90%, 5%, 5%]) + = [10, 10] + +List.shuffle: + description: > + Shuffles the elements of the list in place. + return: + type: 'Void' + description: > + Nothing. + args: + list: + type: '@[T]' + description: > + The mutable reference to the list to be shuffled. + random: + type: 'func(min,max:Int64->Int64)?' + default: 'none' + description: > + If provided, this function will be used to get a random index in the list. Returned + values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number + generation) + example: | + >> list.shuffle() + +List.shuffled: + description: > + Creates a new list with elements shuffled. + return: + type: '[T]' + description: > + A new list with shuffled elements. + args: + list: + type: '[T]' + description: > + The list to be shuffled. + random: + type: 'func(min,max:Int64->Int64)?' + default: 'none' + description: > + If provided, this function will be used to get a random index in the list. Returned + values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number + generation) + example: | + >> [10, 20, 30, 40].shuffled() + = [40, 10, 30, 20] + +List.slice: + description: > + Returns a slice of the list spanning the given indices (inclusive). + return: + type: '[T]' + description: > + A new list spanning the given indices. Note: negative indices are counted from + the back of the list, so `-1` refers to the last element, `-2` the + second-to-last, and so on. + args: + list: + type: '[T]' + description: > + The original list. + from: + type: 'Int' + description: > + The first index to include. + to: + type: 'Int' + description: > + The last index to include. + example: | + >> [10, 20, 30, 40, 50].slice(2, 4) + = [20, 30, 40] + + >> [10, 20, 30, 40, 50].slice(-3, -2) + = [30, 40] + +List.sort: + description: > + Sorts the elements of the list in place in ascending order (small to large). + return: + type: 'Void' + description: > + Nothing. + args: + list: + type: '@[T]' + description: > + The mutable reference to the list to be sorted. + by: + default: 'T.compare' + description: > + The comparison function used to determine order. If not specified, the + default comparison function for the item type will be used. + example: | + list := [40, 10, -30, 20] + list.sort() + >> list + = [-30, 10, 20, 40] + + list.sort(func(a,b:&Int): a.abs() <> b.abs()) + >> list + = [10, 20, -30, 40] + +List.sorted: + description: > + Creates a new list with elements sorted. + return: + type: '[T]' + description: > + A new list with sorted elements. + args: + list: + type: '[T]' + description: > + The list to be sorted. + by: + default: 'T.compare' + description: > + The comparison function used to determine order. If not specified, the + default comparison function for the item type will be used. + example: | + >> [40, 10, -30, 20].sorted() + = [-30, 10, 20, 40] + + >> [40, 10, -30, 20].sorted(func(a,b:&Int): a.abs() <> b.abs()) + = [10, 20, -30, 40] + +List.to: + description: > + Returns a slice of the list from the start of the original list up to a specified index (inclusive). + return: + type: '[T]' + description: > + A new list containing elements from the start up to the specified index. + args: + list: + type: '[T]' + description: > + The original list. + last: + type: 'Int' + description: > + The index up to which elements should be included. + example: | + >> [10, 20, 30, 40, 50].to(3) + = [10, 20, 30] + + >> [10, 20, 30, 40, 50].to(-2) + = [10, 20, 30, 40] + +List.unique: + description: > + Returns a Set that contains the unique elements of the list. + return: + type: '|T|' + description: > + A set containing only unique elements from the list. + args: + list: + type: '[T]' + description: > + The list to process. + example: | + >> [10, 20, 10, 10, 30].unique() + = {10, 20, 30} + diff --git a/api/nums.md b/api/nums.md new file mode 100644 index 00000000..84796a46 --- /dev/null +++ b/api/nums.md @@ -0,0 +1,1233 @@ +% API + +# Builtins + +# Num +## Num.1_PI + +```tomo +Num.1_PI : Num +``` + +The constant $\frac{1}{\pi}$. + +## Num.2_PI + +```tomo +Num.2_PI : Num +``` + +The constant $2 \times \pi$. + +## Num.2_SQRTPI + +```tomo +Num.2_SQRTPI : Num +``` + +The constant $2 \times \sqrt{\pi}$. + +## Num.E + +```tomo +Num.E : Num +``` + +The base of the natural logarithm ($e$). + +## Num.INF + +```tomo +Num.INF : Num +``` + +Positive infinity. + +## Num.LN10 + +```tomo +Num.LN10 : Num +``` + +The natural logarithm of 10. + +## Num.LN2 + +```tomo +Num.LN2 : Num +``` + +The natural logarithm of 2. + +## Num.LOG2E + +```tomo +Num.LOG2E : Num +``` + +The base 2 logarithm of $e$ + +## Num.PI + +```tomo +Num.PI : Num +``` + +Pi ($\pi$). + +## Num.PI_2 + +```tomo +Num.PI_2 : Num +``` + +$\frac{\pi}{2}$ + +## Num.PI_4 + +```tomo +Num.PI_4 : Num +``` + +$\frac{\pi}{4}$ + +## Num.SQRT1_2 + +```tomo +Num.SQRT1_2 : Num +``` + +$\sqrt{\frac{1}{2}}$ + +## Num.SQRT2 + +```tomo +Num.SQRT2 : Num +``` + +$\sqrt{2}$ + +## Num.TAU + +```tomo +Num.TAU : Num +``` + +Tau ($2 \times \pi$) + +## Num.abs + +```tomo +Num.abs : func(n: Num -> Num) +``` + +Calculates the absolute value of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +n | `Num` | The number whose absolute value is to be computed. | + +**Return:** The absolute value of `n`. + + +**Example:** +```tomo +>> (-3.5).abs() += 3.5 + +``` +## Num.acos + +```tomo +Num.acos : func(x: Num -> Num) +``` + +Computes the arc cosine of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the arc cosine is to be calculated. | + +**Return:** The arc cosine of `x` in radians. + + +**Example:** +```tomo +>> (0.0).acos() // -> (π/2) += 1.5708 + +``` +## Num.acosh + +```tomo +Num.acosh : func(x: Num -> Num) +``` + +Computes the inverse hyperbolic cosine of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the inverse hyperbolic cosine is to be calculated. | + +**Return:** The inverse hyperbolic cosine of `x`. + + +**Example:** +```tomo +>> (1.0).acosh() += 0 + +``` +## Num.asin + +```tomo +Num.asin : func(x: Num -> Num) +``` + +Computes the arc sine of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the arc sine is to be calculated. | + +**Return:** The arc sine of `x` in radians. + + +**Example:** +```tomo +>> (0.5).asin() // -> (π/6) += 0.5236 + +``` +## Num.asinh + +```tomo +Num.asinh : func(x: Num -> Num) +``` + +Computes the inverse hyperbolic sine of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the inverse hyperbolic sine is to be calculated. | + +**Return:** The inverse hyperbolic sine of `x`. + + +**Example:** +```tomo +>> (0.0).asinh() += 0 + +``` +## Num.atan + +```tomo +Num.atan : func(x: Num -> Num) +``` + +Computes the arc tangent of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the arc tangent is to be calculated. | + +**Return:** The arc tangent of `x` in radians. + + +**Example:** +```tomo +>> (1.0).atan() // -> (π/4) += 0.7854 + +``` +## Num.atan2 + +```tomo +Num.atan2 : func(x: Num, y: Num -> Num) +``` + +Computes the arc tangent of the quotient of two numbers. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The numerator. | +y | `Num` | The denominator. | + +**Return:** The arc tangent of `x/y` in radians. + + +**Example:** +```tomo +>> Num.atan2(1, 1) // -> (π/4) += 0.7854 + +``` +## Num.atanh + +```tomo +Num.atanh : func(x: Num -> Num) +``` + +Computes the inverse hyperbolic tangent of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the inverse hyperbolic tangent is to be calculated. | + +**Return:** The inverse hyperbolic tangent of `x`. + + +**Example:** +```tomo +>> (0.5).atanh() += 0.5493 + +``` +## Num.cbrt + +```tomo +Num.cbrt : func(x: Num -> Num) +``` + +Computes the cube root of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the cube root is to be calculated. | + +**Return:** The cube root of `x`. + + +**Example:** +```tomo +>> (27.0).cbrt() += 3 + +``` +## Num.ceil + +```tomo +Num.ceil : func(x: Num -> Num) +``` + +Rounds a number up to the nearest integer. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number to be rounded up. | + +**Return:** The smallest integer greater than or equal to `x`. + + +**Example:** +```tomo +>> (3.2).ceil() += 4 + +``` +## Num.clamped + +```tomo +Num.clamped : func(x: Num, low: Num, high: Num -> Num) +``` + +Returns the given number clamped between two values so that it is within that range. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number to clamp. | +low | `Num` | The lowest value the result can take. | +high | `Num` | The highest value the result can take. | + +**Return:** The first argument clamped between the other two arguments. + + +**Example:** +```tomo +>> (2.5).clamped(5.5, 10.5) += 5.5 + +``` +## Num.copysign + +```tomo +Num.copysign : func(x: Num, y: Num -> Num) +``` + +Copies the sign of one number to another. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number whose magnitude will be copied. | +y | `Num` | The number whose sign will be copied. | + +**Return:** A number with the magnitude of `x` and the sign of `y`. + + +**Example:** +```tomo +>> (3.0).copysign(-1) += -3 + +``` +## Num.cos + +```tomo +Num.cos : func(x: Num -> Num) +``` + +Computes the cosine of a number (angle in radians). + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The angle in radians. | + +**Return:** The cosine of `x`. + + +**Example:** +```tomo +>> (0.0).cos() += 1 + +``` +## Num.cosh + +```tomo +Num.cosh : func(x: Num -> Num) +``` + +Computes the hyperbolic cosine of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the hyperbolic cosine is to be calculated. | + +**Return:** The hyperbolic cosine of `x`. + + +**Example:** +```tomo +>> (0.0).cosh() += 1 + +``` +## Num.erf + +```tomo +Num.erf : func(x: Num -> Num) +``` + +Computes the error function of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the error function is to be calculated. | + +**Return:** The error function of `x`. + + +**Example:** +```tomo +>> (0.0).erf() += 0 + +``` +## Num.erfc + +```tomo +Num.erfc : func(x: Num -> Num) +``` + +Computes the complementary error function of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the complementary error function is to be calculated. | + +**Return:** The complementary error function of `x`. + + +**Example:** +```tomo +>> (0.0).erfc() += 1 + +``` +## Num.exp + +```tomo +Num.exp : func(x: Num -> Num) +``` + +Computes the exponential function $e^x$ for a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The exponent. | + +**Return:** The value of $e^x$. + + +**Example:** +```tomo +>> (1.0).exp() += 2.7183 + +``` +## Num.exp2 + +```tomo +Num.exp2 : func(x: Num -> Num) +``` + +Computes $2^x$ for a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The exponent. | + +**Return:** The value of $2^x$. + + +**Example:** +```tomo +>> (3.0).exp2() += 8 + +``` +## Num.expm1 + +```tomo +Num.expm1 : func(x: Num -> Num) +``` + +Computes $e^x - 1$ for a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The exponent. | + +**Return:** The value of $e^x - 1$. + + +**Example:** +```tomo +>> (1.0).expm1() += 1.7183 + +``` +## Num.fdim + +```tomo +Num.fdim : func(x: Num, y: Num -> Num) +``` + +Computes the positive difference between two numbers. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The first number. | +y | `Num` | The second number. | + +**Return:** The positive difference $\max(0, x - y)$. + + +**Example:** +```tomo +fd + +>> (5.0).fdim(3) += 2 + +``` +## Num.floor + +```tomo +Num.floor : func(x: Num -> Num) +``` + +Rounds a number down to the nearest integer. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number to be rounded down. | + +**Return:** The largest integer less than or equal to `x`. + + +**Example:** +```tomo +>> (3.7).floor() += 3 + +``` +## Num.format + +```tomo +Num.format : func(n: Num, precision: Int = 0 -> Text) +``` + +Formats a number as a text with a specified precision. + +Argument | Type | Description | Default +---------|------|-------------|--------- +n | `Num` | The number to be formatted. | +precision | `Int` | The number of decimal places. Default is `0`. | **Default:** `0` + +**Return:** A text representation of the number with the specified precision. + + +**Example:** +```tomo +>> (3.14159).format(precision=2) += "3.14" + +``` +## Num.hypot + +```tomo +Num.hypot : func(x: Num, y: Num -> Num) +``` + +Computes the Euclidean norm, $\sqrt{x^2 + y^2}$, of two numbers. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The first number. | +y | `Num` | The second number. | + +**Return:** The Euclidean norm of `x` and `y`. + + +**Example:** +```tomo +>> Num.hypot(3, 4) += 5 + +``` +## Num.is_between + +```tomo +Num.is_between : func(x: Num, low: Num, high: Num -> Bool) +``` + +Determines if a number is between two numbers (inclusive). + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The integer to be checked. | +low | `Num` | The lower bound to check (inclusive). | +high | `Num` | The upper bound to check (inclusive). | + +**Return:** `yes` if `low <= x and x <= high`, otherwise `no` + + +**Example:** +```tomo +>> (7.5).is_between(1, 10) += yes +>> (7.5).is_between(100, 200) += no +>> (7.5).is_between(1, 7.5) += yes + +``` +## Num.isfinite + +```tomo +Num.isfinite : func(n: Num -> Bool) +``` + +Checks if a number is finite. + +Argument | Type | Description | Default +---------|------|-------------|--------- +n | `Num` | The number to be checked. | + +**Return:** `yes` if `n` is finite, `no` otherwise. + + +**Example:** +```tomo +>> (1.0).isfinite() += yes +>> Num.INF.isfinite() += no + +``` +## Num.isinf + +```tomo +Num.isinf : func(n: Num -> Bool) +``` + +Checks if a number is infinite. + +Argument | Type | Description | Default +---------|------|-------------|--------- +n | `Num` | The number to be checked. | + +**Return:** `yes` if `n` is infinite, `no` otherwise. + + +**Example:** +```tomo +>> Num.INF.isinf() += yes +>> (1.0).isinf() += no + +``` +## Num.j0 + +```tomo +Num.j0 : func(x: Num -> Num) +``` + +Computes the Bessel function of the first kind of order 0. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the Bessel function is to be calculated. | + +**Return:** The Bessel function of the first kind of order 0 of `x`. + + +**Example:** +```tomo +>> (0.0).j0() += 1 + +``` +## Num.j1 + +```tomo +Num.j1 : func(x: Num -> Num) +``` + +Computes the Bessel function of the first kind of order 1. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the Bessel function is to be calculated. | + +**Return:** The Bessel function of the first kind of order 1 of `x`. + + +**Example:** +```tomo +>> (0.0).j1() += 0 + +``` +## Num.log + +```tomo +Num.log : func(x: Num -> Num) +``` + +Computes the natural logarithm (base $e$) of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the natural logarithm is to be calculated. | + +**Return:** The natural logarithm of `x`. + + +**Example:** +```tomo +>> Num.E.log() += 1 + +``` +## Num.log10 + +```tomo +Num.log10 : func(x: Num -> Num) +``` + +Computes the base-10 logarithm of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the base-10 logarithm is to be calculated. | + +**Return:** The base-10 logarithm of `x`. + + +**Example:** +```tomo +>> (100.0).log10() += 2 + +``` +## Num.log1p + +```tomo +Num.log1p : func(x: Num -> Num) +``` + +Computes $\log(1 + x)$ for a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which $\log(1 + x)$ is to be calculated. | + +**Return:** The value of $\log(1 + x)$. + + +**Example:** +```tomo +>> (1.0).log1p() += 0.6931 + +``` +## Num.log2 + +```tomo +Num.log2 : func(x: Num -> Num) +``` + +Computes the base-2 logarithm of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the base-2 logarithm is to be calculated. | + +**Return:** The base-2 logarithm of `x`. + + +**Example:** +```tomo +>> (8.0).log2() += 3 + +``` +## Num.logb + +```tomo +Num.logb : func(x: Num -> Num) +``` + +Computes the binary exponent (base-2 logarithm) of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the binary exponent is to be calculated. | + +**Return:** The binary exponent of `x`. + + +**Example:** +```tomo +>> (8.0).logb() += 3 + +``` +## Num.mix + +```tomo +Num.mix : func(amount: Num, x: Num, y: Num -> Num) +``` + +Interpolates between two numbers based on a given amount. + +Argument | Type | Description | Default +---------|------|-------------|--------- +amount | `Num` | The interpolation factor (between `0` and `1`). | +x | `Num` | The starting number. | +y | `Num` | The ending number. | + +**Return:** The interpolated number between `x` and `y` based on `amount`. + + +**Example:** +```tomo +>> (0.5).mix(10, 20) += 15 +>> (0.25).mix(10, 20) += 12.5 + +``` +## Num.near + +```tomo +Num.near : func(x: Num, y: Num, ratio: Num = 1e-9, min_epsilon: Num = 1e-9 -> Bool) +``` + +Checks if two numbers are approximately equal within specified tolerances. If two numbers are within an absolute difference or the ratio between the two is small enough, they are considered near each other. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The first number. | +y | `Num` | The second number. | +ratio | `Num` | The relative tolerance. Default is `1e-9`. | **Default:** `1e-9` +min_epsilon | `Num` | The absolute tolerance. Default is `1e-9`. | **Default:** `1e-9` + +**Return:** `yes` if `x` and `y` are approximately equal within the specified tolerances, `no` otherwise. + + +**Example:** +```tomo +>> (1.0).near(1.000000001) += yes + +>> (100.0).near(110, ratio=0.1) += yes + +>> (5.0).near(5.1, min_epsilon=0.1) += yes + +``` +## Num.nextafter + +```tomo +Num.nextafter : func(x: Num, y: Num -> Num) +``` + +Computes the next representable value after a given number towards a specified direction. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The starting number. | +y | `Num` | The direction towards which to find the next representable value. | + +**Return:** The next representable value after `x` in the direction of `y`. + + +**Example:** +```tomo +>> (1.0).nextafter(1.1) += 1.0000000000000002 + +``` +## Num.parse + +```tomo +Num.parse : func(text: Text -> Num?) +``` + +Converts a text representation of a number into a floating-point number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text containing the number. | + +**Return:** The number represented by the text or `none` if the entire text can't be parsed as a number. + + +**Example:** +```tomo +>> Num.parse("3.14") += 3.14 +>> Num.parse("1e3") += 1000 + +``` +## Num.percent + +```tomo +Num.percent : func(n: Num, precision: Int = 0 -> Text) +``` + +Convert a number into a percentage text with a percent sign. + +Argument | Type | Description | Default +---------|------|-------------|--------- +n | `Num` | The number to be converted to a percent. | +precision | `Int` | The number of decimal places. Default is `0`. | **Default:** `0` + +**Return:** A text representation of the number as a percentage with a percent sign. + + +**Example:** +```tomo +>> (0.5).percent() += "50%" +>> (1./3.).percent(2) += "33.33%" + +``` +## Num.rint + +```tomo +Num.rint : func(x: Num -> Num) +``` + +Rounds a number to the nearest integer, with ties rounded to the nearest even integer. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number to be rounded. | + +**Return:** The nearest integer value of `x`. + + +**Example:** +```tomo +>> (3.5).rint() += 4 +>> (2.5).rint() += 2 + +``` +## Num.round + +```tomo +Num.round : func(x: Num -> Num) +``` + +Rounds a number to the nearest whole number integer. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number to be rounded. | + +**Return:** The nearest integer value of `x`. + + +**Example:** +```tomo +>> (2.3).round() += 2 +>> (2.7).round() += 3 + +``` +## Num.scientific + +```tomo +Num.scientific : func(n: Num, precision: Int = 0 -> Text) +``` + +Formats a number in scientific notation with a specified precision. + +Argument | Type | Description | Default +---------|------|-------------|--------- +n | `Num` | The number to be formatted. | +precision | `Int` | The number of decimal places. Default is `0`. | **Default:** `0` + +**Return:** A text representation of the number in scientific notation with the specified precision. + + +**Example:** +```tomo +>> (12345.6789).scientific(precision=2) += "1.23e+04" + +``` +## Num.significand + +```tomo +Num.significand : func(x: Num -> Num) +``` + +Extracts the significand (or mantissa) of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number from which to extract the significand. | + +**Return:** The significand of `x`. + + +**Example:** +```tomo +>> (1234.567).significand() += 0.1234567 + +``` +## Num.sin + +```tomo +Num.sin : func(x: Num -> Num) +``` + +Computes the sine of a number (angle in radians). + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The angle in radians. | + +**Return:** The sine of `x`. + + +**Example:** +```tomo +>> (0.0).sin() += 0 + +``` +## Num.sinh + +```tomo +Num.sinh : func(x: Num -> Num) +``` + +Computes the hyperbolic sine of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the hyperbolic sine is to be calculated. | + +**Return:** The hyperbolic sine of `x`. + + +**Example:** +```tomo +>> (0.0).sinh() += 0 + +``` +## Num.sqrt + +```tomo +Num.sqrt : func(x: Num -> Num) +``` + +Computes the square root of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the square root is to be calculated. | + +**Return:** The square root of `x`. + + +**Example:** +```tomo +>> (16.0).sqrt() += 4 + +``` +## Num.tan + +```tomo +Num.tan : func(x: Num -> Num) +``` + +Computes the tangent of a number (angle in radians). + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The angle in radians. | + +**Return:** The tangent of `x`. + + +**Example:** +```tomo +>> (0.0).tan() += 0 + +``` +## Num.tanh + +```tomo +Num.tanh : func(x: Num -> Num) +``` + +Computes the hyperbolic tangent of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the hyperbolic tangent is to be calculated. | + +**Return:** The hyperbolic tangent of `x`. + + +**Example:** +```tomo +>> (0.0).tanh() += 0 + +``` +## Num.tgamma + +```tomo +Num.tgamma : func(x: Num -> Num) +``` + +Computes the gamma function of a number. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the gamma function is to be calculated. | + +**Return:** The gamma function of `x`. + + +**Example:** +```tomo +>> (1.0).tgamma() += 1 + +``` +## Num.trunc + +```tomo +Num.trunc : func(x: Num -> Num) +``` + +Truncates a number to the nearest integer towards zero. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number to be truncated. | + +**Return:** The integer part of `x` towards zero. + + +**Example:** +```tomo +>> (3.7).trunc() += 3 +>> (-3.7).trunc() += -3 + +``` +## Num.y0 + +```tomo +Num.y0 : func(x: Num -> Num) +``` + +Computes the Bessel function of the second kind of order 0. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the Bessel function is to be calculated. | + +**Return:** The Bessel function of the second kind of order 0 of `x`. + + +**Example:** +```tomo +>> (1.0).y0() += -0.7652 + +``` +## Num.y1 + +```tomo +Num.y1 : func(x: Num -> Num) +``` + +Computes the Bessel function of the second kind of order 1. + +Argument | Type | Description | Default +---------|------|-------------|--------- +x | `Num` | The number for which the Bessel function is to be calculated. | + +**Return:** The Bessel function of the second kind of order 1 of `x`. + + +**Example:** +```tomo +>> (1.0).y1() += 0.4401 + +``` diff --git a/api/nums.yaml b/api/nums.yaml new file mode 100644 index 00000000..d69a6b9e --- /dev/null +++ b/api/nums.yaml @@ -0,0 +1,978 @@ +Num.abs: + description: > + Calculates the absolute value of a number. + return: + type: 'Num' + description: > + The absolute value of `n`. + args: + n: + type: 'Num' + description: > + The number whose absolute value is to be computed. + example: | + >> (-3.5).abs() + = 3.5 + +Num.acos: + description: > + Computes the arc cosine of a number. + return: + type: 'Num' + description: > + The arc cosine of `x` in radians. + args: + x: + type: 'Num' + description: > + The number for which the arc cosine is to be calculated. + example: | + >> (0.0).acos() // -> (π/2) + = 1.5708 + +Num.acosh: + description: > + Computes the inverse hyperbolic cosine of a number. + return: + type: 'Num' + description: > + The inverse hyperbolic cosine of `x`. + args: + x: + type: 'Num' + description: > + The number for which the inverse hyperbolic cosine is to be calculated. + example: | + >> (1.0).acosh() + = 0 + +Num.asin: + description: > + Computes the arc sine of a number. + return: + type: 'Num' + description: > + The arc sine of `x` in radians. + args: + x: + type: 'Num' + description: > + The number for which the arc sine is to be calculated. + example: | + >> (0.5).asin() // -> (π/6) + = 0.5236 + +Num.asinh: + description: > + Computes the inverse hyperbolic sine of a number. + return: + type: 'Num' + description: > + The inverse hyperbolic sine of `x`. + args: + x: + type: 'Num' + description: > + The number for which the inverse hyperbolic sine is to be calculated. + example: | + >> (0.0).asinh() + = 0 + +Num.atan: + description: > + Computes the arc tangent of a number. + return: + type: 'Num' + description: > + The arc tangent of `x` in radians. + args: + x: + type: 'Num' + description: > + The number for which the arc tangent is to be calculated. + example: | + >> (1.0).atan() // -> (π/4) + = 0.7854 + +Num.atan2: + description: > + Computes the arc tangent of the quotient of two numbers. + return: + type: 'Num' + description: > + The arc tangent of `x/y` in radians. + args: + x: + type: 'Num' + description: > + The numerator. + y: + type: 'Num' + description: > + The denominator. + example: | + >> Num.atan2(1, 1) // -> (π/4) + = 0.7854 + +Num.atanh: + description: > + Computes the inverse hyperbolic tangent of a number. + return: + type: 'Num' + description: > + The inverse hyperbolic tangent of `x`. + args: + x: + type: 'Num' + description: > + The number for which the inverse hyperbolic tangent is to be calculated. + example: | + >> (0.5).atanh() + = 0.5493 + +Num.cbrt: + description: > + Computes the cube root of a number. + return: + type: 'Num' + description: > + The cube root of `x`. + args: + x: + type: 'Num' + description: > + The number for which the cube root is to be calculated. + example: | + >> (27.0).cbrt() + = 3 + +Num.ceil: + description: > + Rounds a number up to the nearest integer. + return: + type: 'Num' + description: > + The smallest integer greater than or equal to `x`. + args: + x: + type: 'Num' + description: > + The number to be rounded up. + example: | + >> (3.2).ceil() + = 4 + +Num.clamped: + description: > + Returns the given number clamped between two values so that it is within + that range. + return: + type: 'Num' + description: > + The first argument clamped between the other two arguments. + args: + x: + type: 'Num' + description: > + The number to clamp. + low: + type: 'Num' + description: > + The lowest value the result can take. + high: + type: 'Num' + description: > + The highest value the result can take. + example: | + >> (2.5).clamped(5.5, 10.5) + = 5.5 + +Num.copysign: + description: > + Copies the sign of one number to another. + return: + type: 'Num' + description: > + A number with the magnitude of `x` and the sign of `y`. + args: + x: + type: 'Num' + description: > + The number whose magnitude will be copied. + y: + type: 'Num' + description: > + The number whose sign will be copied. + example: | + >> (3.0).copysign(-1) + = -3 + +Num.cos: + description: > + Computes the cosine of a number (angle in radians). + return: + type: 'Num' + description: > + The cosine of `x`. + args: + x: + type: 'Num' + description: > + The angle in radians. + example: | + >> (0.0).cos() + = 1 + +Num.cosh: + description: > + Computes the hyperbolic cosine of a number. + return: + type: 'Num' + description: > + The hyperbolic cosine of `x`. + args: + x: + type: 'Num' + description: > + The number for which the hyperbolic cosine is to be calculated. + example: | + >> (0.0).cosh() + = 1 + +Num.erf: + description: > + Computes the error function of a number. + return: + type: 'Num' + description: > + The error function of `x`. + args: + x: + type: 'Num' + description: > + The number for which the error function is to be calculated. + example: | + >> (0.0).erf() + = 0 + +Num.erfc: + description: > + Computes the complementary error function of a number. + return: + type: 'Num' + description: > + The complementary error function of `x`. + args: + x: + type: 'Num' + description: > + The number for which the complementary error function is to be calculated. + example: | + >> (0.0).erfc() + = 1 + +Num.exp: + description: > + Computes the exponential function $e^x$ for a number. + return: + type: 'Num' + description: > + The value of $e^x$. + args: + x: + type: 'Num' + description: > + The exponent. + example: | + >> (1.0).exp() + = 2.7183 + +Num.exp2: + description: > + Computes $2^x$ for a number. + return: + type: 'Num' + description: > + The value of $2^x$. + args: + x: + type: 'Num' + description: > + The exponent. + example: | + >> (3.0).exp2() + = 8 + +Num.expm1: + description: > + Computes $e^x - 1$ for a number. + return: + type: 'Num' + description: > + The value of $e^x - 1$. + args: + x: + type: 'Num' + description: > + The exponent. + example: | + >> (1.0).expm1() + = 1.7183 + +Num.fdim: + description: > + Computes the positive difference between two numbers. + return: + type: 'Num' + description: > + The positive difference $\max(0, x - y)$. + args: + x: + type: 'Num' + description: > + The first number. + y: + type: 'Num' + description: > + The second number. + example: | + fd + + >> (5.0).fdim(3) + = 2 + +Num.floor: + description: > + Rounds a number down to the nearest integer. + return: + type: 'Num' + description: > + The largest integer less than or equal to `x`. + args: + x: + type: 'Num' + description: > + The number to be rounded down. + example: | + >> (3.7).floor() + = 3 + +Num.format: + description: > + Formats a number as a text with a specified precision. + return: + type: 'Text' + description: > + A text representation of the number with the specified precision. + args: + n: + type: 'Num' + description: > + The number to be formatted. + precision: + type: 'Int' + default: '0' + description: > + The number of decimal places. Default is `0`. + example: | + >> (3.14159).format(precision=2) + = "3.14" + +Num.hypot: + description: > + Computes the Euclidean norm, $\sqrt{x^2 + y^2}$, of two numbers. + return: + type: 'Num' + description: > + The Euclidean norm of `x` and `y`. + args: + x: + type: 'Num' + description: > + The first number. + y: + type: 'Num' + description: > + The second number. + example: | + >> Num.hypot(3, 4) + = 5 + +Num.isfinite: + description: > + Checks if a number is finite. + return: + type: 'Bool' + description: > + `yes` if `n` is finite, `no` otherwise. + args: + n: + type: 'Num' + description: > + The number to be checked. + example: | + >> (1.0).isfinite() + = yes + >> Num.INF.isfinite() + = no + +Num.is_between: + description: > + Determines if a number is between two numbers (inclusive). + return: + type: 'Bool' + description: > + `yes` if `low <= x and x <= high`, otherwise `no` + args: + x: + type: 'Num' + description: > + The integer to be checked. + low: + type: 'Num' + description: > + The lower bound to check (inclusive). + high: + type: 'Num' + description: > + The upper bound to check (inclusive). + example: | + >> (7.5).is_between(1, 10) + = yes + >> (7.5).is_between(100, 200) + = no + >> (7.5).is_between(1, 7.5) + = yes + +Num.isinf: + description: > + Checks if a number is infinite. + return: + type: 'Bool' + description: > + `yes` if `n` is infinite, `no` otherwise. + args: + n: + type: 'Num' + description: > + The number to be checked. + example: | + >> Num.INF.isinf() + = yes + >> (1.0).isinf() + = no + +Num.j0: + description: > + Computes the Bessel function of the first kind of order 0. + return: + type: 'Num' + description: > + The Bessel function of the first kind of order 0 of `x`. + args: + x: + type: 'Num' + description: > + The number for which the Bessel function is to be calculated. + example: | + >> (0.0).j0() + = 1 + +Num.j1: + description: > + Computes the Bessel function of the first kind of order 1. + return: + type: 'Num' + description: > + The Bessel function of the first kind of order 1 of `x`. + args: + x: + type: 'Num' + description: > + The number for which the Bessel function is to be calculated. + example: | + >> (0.0).j1() + = 0 + +Num.log: + description: > + Computes the natural logarithm (base $e$) of a number. + return: + type: 'Num' + description: > + The natural logarithm of `x`. + args: + x: + type: 'Num' + description: > + The number for which the natural logarithm is to be calculated. + example: | + >> Num.E.log() + = 1 + +Num.log10: + description: > + Computes the base-10 logarithm of a number. + return: + type: 'Num' + description: > + The base-10 logarithm of `x`. + args: + x: + type: 'Num' + description: > + The number for which the base-10 logarithm is to be calculated. + example: | + >> (100.0).log10() + = 2 + +Num.log1p: + description: > + Computes $\log(1 + x)$ for a number. + return: + type: 'Num' + description: > + The value of $\log(1 + x)$. + args: + x: + type: 'Num' + description: > + The number for which $\log(1 + x)$ is to be calculated. + example: | + >> (1.0).log1p() + = 0.6931 + +Num.log2: + description: > + Computes the base-2 logarithm of a number. + return: + type: 'Num' + description: > + The base-2 logarithm of `x`. + args: + x: + type: 'Num' + description: > + The number for which the base-2 logarithm is to be calculated. + example: | + >> (8.0).log2() + = 3 + +Num.logb: + description: > + Computes the binary exponent (base-2 logarithm) of a number. + return: + type: 'Num' + description: > + The binary exponent of `x`. + args: + x: + type: 'Num' + description: > + The number for which the binary exponent is to be calculated. + example: | + >> (8.0).logb() + = 3 + +Num.mix: + description: > + Interpolates between two numbers based on a given amount. + return: + type: 'Num' + description: > + The interpolated number between `x` and `y` based on `amount`. + args: + amount: + type: 'Num' + description: > + The interpolation factor (between `0` and `1`). + x: + type: 'Num' + description: > + The starting number. + y: + type: 'Num' + description: > + The ending number. + example: | + >> (0.5).mix(10, 20) + = 15 + >> (0.25).mix(10, 20) + = 12.5 + +Num.near: + description: > + Checks if two numbers are approximately equal within specified tolerances. If + two numbers are within an absolute difference or the ratio between the two is + small enough, they are considered near each other. + return: + type: 'Bool' + description: > + `yes` if `x` and `y` are approximately equal within the specified tolerances, `no` otherwise. + args: + x: + type: 'Num' + description: > + The first number. + y: + type: 'Num' + description: > + The second number. + ratio: + type: 'Num' + default: '1e-9' + description: > + The relative tolerance. Default is `1e-9`. + min_epsilon: + type: 'Num' + default: '1e-9' + description: > + The absolute tolerance. Default is `1e-9`. + example: | + >> (1.0).near(1.000000001) + = yes + + >> (100.0).near(110, ratio=0.1) + = yes + + >> (5.0).near(5.1, min_epsilon=0.1) + = yes + +Num.nextafter: + description: > + Computes the next representable value after a given number towards a specified direction. + return: + type: 'Num' + description: > + The next representable value after `x` in the direction of `y`. + args: + x: + type: 'Num' + description: > + The starting number. + y: + type: 'Num' + description: > + The direction towards which to find the next representable value. + example: | + >> (1.0).nextafter(1.1) + = 1.0000000000000002 + +Num.parse: + description: > + Converts a text representation of a number into a floating-point number. + return: + type: 'Num?' + description: > + The number represented by the text or `none` if the entire text can't be parsed + as a number. + args: + text: + type: 'Text' + description: > + The text containing the number. + example: | + >> Num.parse("3.14") + = 3.14 + >> Num.parse("1e3") + = 1000 + +Num.percent: + description: > + Convert a number into a percentage text with a percent sign. + return: + type: 'Text' + description: > + A text representation of the number as a percentage with a percent sign. + args: + n: + type: 'Num' + description: > + The number to be converted to a percent. + precision: + type: 'Int' + default: '0' + description: > + The number of decimal places. Default is `0`. + example: | + >> (0.5).percent() + = "50%" + >> (1./3.).percent(2) + = "33.33%" + +Num.rint: + description: > + Rounds a number to the nearest integer, with ties rounded to the nearest even integer. + return: + type: 'Num' + description: > + The nearest integer value of `x`. + args: + x: + type: 'Num' + description: > + The number to be rounded. + example: | + >> (3.5).rint() + = 4 + >> (2.5).rint() + = 2 + +Num.round: + description: > + Rounds a number to the nearest whole number integer. + return: + type: 'Num' + description: > + The nearest integer value of `x`. + args: + x: + type: 'Num' + description: > + The number to be rounded. + example: | + >> (2.3).round() + = 2 + >> (2.7).round() + = 3 + +Num.scientific: + description: > + Formats a number in scientific notation with a specified precision. + return: + type: 'Text' + description: > + A text representation of the number in scientific notation with the specified precision. + args: + n: + type: 'Num' + description: > + The number to be formatted. + precision: + type: 'Int' + default: '0' + description: > + The number of decimal places. Default is `0`. + example: | + >> (12345.6789).scientific(precision=2) + = "1.23e+04" + +Num.significand: + description: > + Extracts the significand (or mantissa) of a number. + return: + type: 'Num' + description: > + The significand of `x`. + args: + x: + type: 'Num' + description: > + The number from which to extract the significand. + example: | + >> (1234.567).significand() + = 0.1234567 + +Num.sin: + description: > + Computes the sine of a number (angle in radians). + return: + type: 'Num' + description: > + The sine of `x`. + args: + x: + type: 'Num' + description: > + The angle in radians. + example: | + >> (0.0).sin() + = 0 + +Num.sinh: + description: > + Computes the hyperbolic sine of a number. + return: + type: 'Num' + description: > + The hyperbolic sine of `x`. + args: + x: + type: 'Num' + description: > + The number for which the hyperbolic sine is to be calculated. + example: | + >> (0.0).sinh() + = 0 + +Num.sqrt: + description: > + Computes the square root of a number. + return: + type: 'Num' + description: > + The square root of `x`. + args: + x: + type: 'Num' + description: > + The number for which the square root is to be calculated. + example: | + >> (16.0).sqrt() + = 4 + +Num.tan: + description: > + Computes the tangent of a number (angle in radians). + return: + type: 'Num' + description: > + The tangent of `x`. + args: + x: + type: 'Num' + description: > + The angle in radians. + example: | + >> (0.0).tan() + = 0 + +Num.tanh: + description: > + Computes the hyperbolic tangent of a number. + return: + type: 'Num' + description: > + The hyperbolic tangent of `x`. + args: + x: + type: 'Num' + description: > + The number for which the hyperbolic tangent is to be calculated. + example: | + >> (0.0).tanh() + = 0 + +Num.tgamma: + description: > + Computes the gamma function of a number. + return: + type: 'Num' + description: > + The gamma function of `x`. + args: + x: + type: 'Num' + description: > + The number for which the gamma function is to be calculated. + example: | + >> (1.0).tgamma() + = 1 + +Num.trunc: + description: > + Truncates a number to the nearest integer towards zero. + return: + type: 'Num' + description: > + The integer part of `x` towards zero. + args: + x: + type: 'Num' + description: > + The number to be truncated. + example: | + >> (3.7).trunc() + = 3 + >> (-3.7).trunc() + = -3 + +Num.y0: + description: > + Computes the Bessel function of the second kind of order 0. + return: + type: 'Num' + description: > + The Bessel function of the second kind of order 0 of `x`. + args: + x: + type: 'Num' + description: > + The number for which the Bessel function is to be calculated. + example: | + >> (1.0).y0() + = -0.7652 + +Num.y1: + description: > + Computes the Bessel function of the second kind of order 1. + return: + type: 'Num' + description: > + The Bessel function of the second kind of order 1 of `x`. + args: + x: + type: 'Num' + description: > + The number for which the Bessel function is to be calculated. + example: | + >> (1.0).y1() + = 0.4401 + + +Num.1_PI: + type: Num + description: > + The constant $\frac{1}{\pi}$. +Num.2_PI: + type: Num + description: > + The constant $2 \times \pi$. +Num.2_SQRTPI: + type: Num + description: > + The constant $2 \times \sqrt{\pi}$. +Num.E: + type: Num + description: > + The base of the natural logarithm ($e$). +Num.INF: + type: Num + description: > + Positive infinity. +Num.LN10: + type: Num + description: > + The natural logarithm of 10. +Num.LN2: + type: Num + description: > + The natural logarithm of 2. +Num.LOG2E: + type: Num + description: > + The base 2 logarithm of $e$ +Num.PI: + type: Num + description: > + Pi ($\pi$). +Num.PI_2: + type: Num + description: > + $\frac{\pi}{2}$ +Num.PI_4: + type: Num + description: > + $\frac{\pi}{4}$ +Num.SQRT1_2: + type: Num + description: > + $\sqrt{\frac{1}{2}}$ +Num.SQRT2: + type: Num + description: > + $\sqrt{2}$ +Num.TAU: + type: Num + description: > + Tau ($2 \times \pi$) diff --git a/api/paths.md b/api/paths.md new file mode 100644 index 00000000..8e62f079 --- /dev/null +++ b/api/paths.md @@ -0,0 +1,936 @@ +% API + +# Builtins + +# Path +## Path.accessed + +```tomo +Path.accessed : func(path: Path, follow_symlinks: Bool = yes -> Int64?) +``` + +Gets the file access time of a file. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file whose access time you want. | +follow_symlinks | `Bool` | Whether to follow symbolic links. | **Default:** `yes` + +**Return:** A 64-bit unix epoch timestamp representing when the file or directory was last accessed, or `none` if no such file or directory exists. + + +**Example:** +```tomo +>> (./file.txt).accessed() += 1704221100? +>> (./not-a-file).accessed() += none + +``` +## Path.append + +```tomo +Path.append : func(path: Path, text: Text, permissions: Int32 = Int32(0o644) -> Void) +``` + +Appends the given text to the file at the specified path, creating the file if it doesn't already exist. Failure to write will result in a runtime error. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file to append to. | +text | `Text` | The text to append to the file. | +permissions | `Int32` | The permissions to set on the file if it is being created. | **Default:** `Int32(0o644)` + +**Return:** Nothing. + + +**Example:** +```tomo +(./log.txt).append("extra line$(\n)") + +``` +## Path.append_bytes + +```tomo +Path.append_bytes : func(path: Path, bytes: [Byte], permissions: Int32 = Int32(0o644) -> Void) +``` + +Appends the given bytes to the file at the specified path, creating the file if it doesn't already exist. Failure to write will result in a runtime error. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file to append to. | +bytes | `[Byte]` | The bytes to append to the file. | +permissions | `Int32` | The permissions to set on the file if it is being created. | **Default:** `Int32(0o644)` + +**Return:** Nothing. + + +**Example:** +```tomo +(./log.txt).append_bytes([104, 105]) + +``` +## Path.base_name + +```tomo +Path.base_name : func(path: Path -> Text) +``` + +Returns the base name of the file or directory at the specified path. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file or directory. | + +**Return:** The base name of the file or directory. + + +**Example:** +```tomo +>> (./path/to/file.txt).base_name() += "file.txt" + +``` +## Path.by_line + +```tomo +Path.by_line : func(path: Path -> func(->Text?)?) +``` + +Returns an iterator that can be used to iterate over a file one line at a time, or returns a null value if the file could not be opened. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file. | + +**Return:** An iterator that can be used to get lines from a file one at a time or a null value if the file couldn't be read. + + +**Example:** +```tomo +# Safely handle file not being readable: +if lines := (./file.txt).by_line() +for line in lines +say(line.upper()) +else +say("Couldn't read file!") + +# Assume the file is readable and error if that's not the case: +for line in (/dev/stdin).by_line()! +say(line.upper()) + +``` +## Path.can_execute + +```tomo +Path.can_execute : func(path: Path -> Bool) +``` + +Returns whether or not a file can be executed by the current user/group. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file to check. | + +**Return:** `yes` if the file or directory exists and the current user has execute permissions, otherwise `no`. + + +**Example:** +```tomo +>> (/bin/sh).can_execute() += yes +>> (/usr/include/stdlib.h).can_execute() += no +>> (/non/existant/file).can_execute() += no + +``` +## Path.can_read + +```tomo +Path.can_read : func(path: Path -> Bool) +``` + +Returns whether or not a file can be read by the current user/group. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file to check. | + +**Return:** `yes` if the file or directory exists and the current user has read permissions, otherwise `no`. + + +**Example:** +```tomo +>> (/usr/include/stdlib.h).can_read() += yes +>> (/etc/shadow).can_read() += no +>> (/non/existant/file).can_read() += no + +``` +## Path.can_write + +```tomo +Path.can_write : func(path: Path -> Bool) +``` + +Returns whether or not a file can be written by the current user/group. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file to check. | + +**Return:** `yes` if the file or directory exists and the current user has write permissions, otherwise `no`. + + +**Example:** +```tomo +>> (/tmp).can_write() += yes +>> (/etc/passwd).can_write() += no +>> (/non/existant/file).can_write() += no + +``` +## Path.changed + +```tomo +Path.changed : func(path: Path, follow_symlinks: Bool = yes -> Int64?) +``` + +Gets the file change time of a file. + +This is the ["ctime"](https://en.wikipedia.org/wiki/Stat_(system_call)#ctime) of a file, which is _not_ the file creation time. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file whose change time you want. | +follow_symlinks | `Bool` | Whether to follow symbolic links. | **Default:** `yes` + +**Return:** A 64-bit unix epoch timestamp representing when the file or directory was last changed, or `none` if no such file or directory exists. + + +**Example:** +```tomo +>> (./file.txt).changed() += 1704221100? +>> (./not-a-file).changed() += none + +``` +## Path.child + +```tomo +Path.child : func(path: Path, child: Text -> [Path]) +``` + +Return a path that is a child of another path. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of a directory. | +child | `Text` | The name of a child file or directory. | + +**Return:** A new path representing the child. + + +**Example:** +```tomo +>> (./directory).child("file.txt") += (./directory/file.txt) + +``` +## Path.children + +```tomo +Path.children : func(path: Path, include_hidden = no -> [Path]) +``` + +Returns a list of children (files and directories) within the directory at the specified path. Optionally includes hidden files. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the directory. | +include_hidden | `` | Whether to include hidden files, which start with a `.`. | **Default:** `no` + +**Return:** A list of paths for the children. + + +**Example:** +```tomo +>> (./directory).children(include_hidden=yes) += [".git", "foo.txt"] + +``` +## Path.create_directory + +```tomo +Path.create_directory : func(path: Path, permissions = Int32(0o755) -> Void) +``` + +Creates a new directory at the specified path with the given permissions. If any of the parent directories do not exist, they will be created as needed. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the directory to create. | +permissions | `` | The permissions to set on the new directory. | **Default:** `Int32(0o755)` + +**Return:** Nothing. + + +**Example:** +```tomo +(./new_directory).create_directory() + +``` +## Path.current_dir + +```tomo +Path.current_dir : func(-> Path) +``` + +Creates a new directory at the specified path with the given permissions. If any of the parent directories do not exist, they will be created as needed. + + +**Return:** The absolute path of the current directory. + + +**Example:** +```tomo +>> Path.current_dir() += (/home/user/tomo) + +``` +## Path.exists + +```tomo +Path.exists : func(path: Path -> Bool) +``` + +Checks if a file or directory exists at the specified path. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path to check. | + +**Return:** `True` if the file or directory exists, `False` otherwise. + + +**Example:** +```tomo +>> (/).exists() += yes + +``` +## Path.expand_home + +```tomo +Path.expand_home : func(path: Path -> Path) +``` + +For home-based paths (those starting with `~`), expand the path to replace the tilde with and absolute path to the user's `$HOME` directory. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path to expand. | + +**Return:** If the path does not start with a `~`, then return it unmodified. Otherwise, replace the `~` with an absolute path to the user's home directory. + + +**Example:** +```tomo +>> (~/foo).expand_home() # Assume current user is 'user' += /home/user/foo +>> (/foo).expand_home() # No change += /foo + +``` +## Path.extension + +```tomo +Path.extension : func(path: Path, full: Bool = yes -> Text) +``` + +Returns the file extension of the file at the specified path. Optionally returns the full extension. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file. | +full | `Bool` | Whether to return everything after the first `.` in the base name, or only the last part of the extension. | **Default:** `yes` + +**Return:** The file extension (not including the leading `.`) or an empty text if there is no file extension. + + +**Example:** +```tomo +>> (./file.tar.gz).extension() += "tar.gz" +>> (./file.tar.gz).extension(full=no) += "gz" +>> (/foo).extension() += "" +>> (./.git).extension() += "" + +``` +## Path.files + +```tomo +Path.files : func(path: Path, include_hidden: Bool = no -> [Path]) +``` + +Returns a list of files within the directory at the specified path. Optionally includes hidden files. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the directory. | +include_hidden | `Bool` | Whether to include hidden files. | **Default:** `no` + +**Return:** A list of file paths. + + +**Example:** +```tomo +>> (./directory).files(include_hidden=yes) += [(./directory/file1.txt), (./directory/file2.txt)] + +``` +## Path.from_components + +```tomo +Path.from_components : func(components: [Text] -> Path) +``` + +Returns a path built from a list of path components. + +Argument | Type | Description | Default +---------|------|-------------|--------- +components | `[Text]` | A list of path components. | + +**Return:** A path representing the given components. + + +**Example:** +```tomo +>> Path.from_components(["/", "usr", "include"]) += /usr/include +>> Path.from_components(["foo.txt"]) += ./foo.txt +>> Path.from_components(["~", ".local"]) += ~/.local + +``` +## Path.glob + +```tomo +Path.glob : func(path: Path -> [Path]) +``` + +Perform a globbing operation and return a list of matching paths. Some glob specific details: +- The paths "." and ".." are *not* included in any globbing results. +- Files or directories that begin with "." will not match `*`, but will match `.*`. +- Globs do support `{a,b}` syntax for matching files that match any of several + choices of patterns. + +- The shell-style syntax `**` for matching subdirectories is not supported. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the directory which may contain special globbing characters like `*`, `?`, or `{...}` | + +**Return:** A list of file paths that match the glob. + + +**Example:** +```tomo +# Current directory includes: foo.txt, baz.txt, qux.jpg, .hidden +>> (./*).glob() += [(./foo.txt), (./baz.txt), (./qux.jpg)] + +>> (./*.txt).glob() += [(./foo.txt), (./baz.txt)] + +>> (./*.{txt,jpg}).glob() += [(./foo.txt), (./baz.txt), (./qux.jpg)] + +>> (./.*).glob() += [(./.hidden)] + +# Globs with no matches return an empty list: +>> (./*.xxx).glob() += [] + +``` +## Path.group + +```tomo +Path.group : func(path: Path, follow_symlinks: Bool = yes -> Text?) +``` + +Get the owning group of a file or directory. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path whose owning group to get. | +follow_symlinks | `Bool` | Whether to follow symbolic links. | **Default:** `yes` + +**Return:** The name of the group which owns the file or directory, or `none` if the path does not exist. + + +**Example:** +```tomo +>> (/bin).group() += "root" +>> (/non/existent/file).group() += none + +``` +## Path.is_directory + +```tomo +Path.is_directory : func(path: Path, follow_symlinks = yes -> Bool) +``` + +Checks if the path represents a directory. Optionally follows symbolic links. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path to check. | +follow_symlinks | `` | Whether to follow symbolic links. | **Default:** `yes` + +**Return:** `True` if the path is a directory, `False` otherwise. + + +**Example:** +```tomo +>> (./directory/).is_directory() += yes + +>> (./file.txt).is_directory() += no + +``` +## Path.is_file + +```tomo +Path.is_file : func(path: Path, follow_symlinks = yes -> Bool) +``` + +Checks if the path represents a file. Optionally follows symbolic links. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path to check. | +follow_symlinks | `` | Whether to follow symbolic links. | **Default:** `yes` + +**Return:** `True` if the path is a file, `False` otherwise. + + +**Example:** +```tomo +>> (./file.txt).is_file() += yes + +>> (./directory/).is_file() += no + +``` +## Path.is_socket + +```tomo +Path.is_socket : func(path: Path, follow_symlinks = yes -> Bool) +``` + +Checks if the path represents a socket. Optionally follows symbolic links. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path to check. | +follow_symlinks | `` | Whether to follow symbolic links. | **Default:** `yes` + +**Return:** `True` if the path is a socket, `False` otherwise. + + +**Example:** +```tomo +>> (./socket).is_socket() += yes + +``` +## Path.is_symlink + +```tomo +Path.is_symlink : func(path: Path -> Bool) +``` + +Checks if the path represents a symbolic link. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path to check. | + +**Return:** `True` if the path is a symbolic link, `False` otherwise. + + +**Example:** +```tomo +>> (./link).is_symlink() += yes + +``` +## Path.modified + +```tomo +Path.modified : func(path: Path, follow_symlinks: Bool = yes -> Int64?) +``` + +Gets the file modification time of a file. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file whose modification time you want. | +follow_symlinks | `Bool` | Whether to follow symbolic links. | **Default:** `yes` + +**Return:** A 64-bit unix epoch timestamp representing when the file or directory was last modified, or `none` if no such file or directory exists. + + +**Example:** +```tomo +>> (./file.txt).modified() += 1704221100? +>> (./not-a-file).modified() += none + +``` +## Path.owner + +```tomo +Path.owner : func(path: Path, follow_symlinks: Bool = yes -> Text?) +``` + +Get the owning user of a file or directory. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path whose owner to get. | +follow_symlinks | `Bool` | Whether to follow symbolic links. | **Default:** `yes` + +**Return:** The name of the user who owns the file or directory, or `none` if the path does not exist. + + +**Example:** +```tomo +>> (/bin).owner() += "root" +>> (/non/existent/file).owner() += none + +``` +## Path.parent + +```tomo +Path.parent : func(path: Path -> Path) +``` + +Returns the parent directory of the file or directory at the specified path. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file or directory. | + +**Return:** The path of the parent directory. + + +**Example:** +```tomo +>> (./path/to/file.txt).parent() += (./path/to/) + +``` +## Path.read + +```tomo +Path.read : func(path: Path -> Text?) +``` + +Reads the contents of the file at the specified path or a null value if the file could not be read. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file to read. | + +**Return:** The contents of the file. If the file could not be read, a null value will be returned. If the file can be read, but is not valid UTF8 data, an error will be raised. + + +**Example:** +```tomo +>> (./hello.txt).read() += "Hello"? + +>> (./nosuchfile.xxx).read() += none + +``` +## Path.read_bytes + +```tomo +Path.read_bytes : func(path: Path, limit: Int? = none -> [Byte]?) +``` + +Reads the contents of the file at the specified path or a null value if the file could not be read. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file to read. | +limit | `Int?` | A limit to how many bytes should be read. | **Default:** `none` + +**Return:** The byte contents of the file. If the file cannot be read, a null value will be returned. + + +**Example:** +```tomo +>> (./hello.txt).read() += [72, 101, 108, 108, 111]? + +>> (./nosuchfile.xxx).read() += none + +``` +## Path.relative_to + +```tomo +Path.relative_to : func(path: Path, relative_to = (./) -> Path) +``` + +Returns the path relative to a given base path. By default, the base path is the current directory. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path to convert. | +relative_to | `` | The base path for the relative path. | **Default:** `(./)` + +**Return:** The relative path. + + +**Example:** +```tomo +>> (./path/to/file.txt).relative(relative_to=(./path)) += (./to/file.txt) + +``` +## Path.remove + +```tomo +Path.remove : func(path: Path, ignore_missing = no -> Void) +``` + +Removes the file or directory at the specified path. A runtime error is raised if something goes wrong. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path to remove. | +ignore_missing | `` | Whether to ignore errors if the file or directory does not exist. | **Default:** `no` + +**Return:** Nothing. + + +**Example:** +```tomo +(./file.txt).remove() + +``` +## Path.resolved + +```tomo +Path.resolved : func(path: Path, relative_to = (./) -> Path) +``` + +Resolves the absolute path of the given path relative to a base path. By default, the base path is the current directory. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path to resolve. | +relative_to | `` | The base path for resolution. | **Default:** `(./)` + +**Return:** The resolved absolute path. + + +**Example:** +```tomo +>> (~/foo).resolved() += (/home/user/foo) + +>> (./path/to/file.txt).resolved(relative_to=(/foo)) += (/foo/path/to/file.txt) + +``` +## Path.set_owner + +```tomo +Path.set_owner : func(path: Path, owner: Text? = none, group: Text? = none, follow_symlinks: Bool = yes -> Void) +``` + +Set the owning user and/or group for a path. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path to change the permissions for. | +owner | `Text?` | If non-none, the new user to assign to be the owner of the file. | **Default:** `none` +group | `Text?` | If non-none, the new group to assign to be the owner of the file. | **Default:** `none` +follow_symlinks | `Bool` | Whether to follow symbolic links. | **Default:** `yes` + +**Return:** Nothing. If a path does not exist, a failure will be raised. + + +**Example:** +```tomo +(./file.txt).set_owner(owner="root", group="wheel") + +``` +## Path.subdirectories + +```tomo +Path.subdirectories : func(path: Path, include_hidden = no -> [Path]) +``` + +Returns a list of subdirectories within the directory at the specified path. Optionally includes hidden subdirectories. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the directory. | +include_hidden | `` | Whether to include hidden subdirectories. | **Default:** `no` + +**Return:** A list of subdirectory paths. + + +**Example:** +```tomo +>> (./directory).subdirectories() += [(./directory/subdir1), (./directory/subdir2)] + +>> (./directory).subdirectories(include_hidden=yes) += [(./directory/.git), (./directory/subdir1), (./directory/subdir2)] + +``` +## Path.unique_directory + +```tomo +Path.unique_directory : func(path: Path -> Path) +``` + +Generates a unique directory path based on the given path. Useful for creating temporary directories. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The base path for generating the unique directory. The last six letters of this path must be `XXXXXX`. | + +**Return:** A unique directory path after creating the directory. + + +**Example:** +```tomo +>> created := (/tmp/my-dir.XXXXXX).unique_directory() += (/tmp/my-dir-AwoxbM/) +>> created.is_directory() += yes +created.remove() + +``` +## Path.write + +```tomo +Path.write : func(path: Path, text: Text, permissions = Int32(0o644) -> Void) +``` + +Writes the given text to the file at the specified path, creating the file if it doesn't already exist. Sets the file permissions as specified. If the file writing cannot be successfully completed, a runtime error is raised. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file to write to. | +text | `Text` | The text to write to the file. | +permissions | `` | The permissions to set on the file if it is created. | **Default:** `Int32(0o644)` + +**Return:** Nothing. + + +**Example:** +```tomo +(./file.txt).write("Hello, world!") + +``` +## Path.write_bytes + +```tomo +Path.write_bytes : func(path: Path, bytes: [Byte], permissions = Int32(0o644) -> Void) +``` + +Writes the given bytes to the file at the specified path, creating the file if it doesn't already exist. Sets the file permissions as specified. If the file writing cannot be successfully completed, a runtime error is raised. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The path of the file to write to. | +bytes | `[Byte]` | A list of bytes to write to the file. | +permissions | `` | The permissions to set on the file if it is created. | **Default:** `Int32(0o644)` + +**Return:** Nothing. + + +**Example:** +```tomo +(./file.txt).write_bytes([104, 105]) + +``` +## Path.write_unique + +```tomo +Path.write_unique : func(path: Path, text: Text -> Path) +``` + +Writes the given text to a unique file path based on the specified path. The file is created if it doesn't exist. This is useful for creating temporary files. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The base path for generating the unique file. This path must include the string `XXXXXX` in the file base name. | +text | `Text` | The text to write to the file. | + +**Return:** The path of the newly created unique file. + + +**Example:** +```tomo +>> created := (./file-XXXXXX.txt).write_unique("Hello, world!") += (./file-27QHtq.txt) +>> created.read() += "Hello, world!" +created.remove() + +``` +## Path.write_unique_bytes + +```tomo +Path.write_unique_bytes : func(path: Path, bytes: [Byte] -> Path) +``` + +Writes the given bytes to a unique file path based on the specified path. The file is created if it doesn't exist. This is useful for creating temporary files. + +Argument | Type | Description | Default +---------|------|-------------|--------- +path | `Path` | The base path for generating the unique file. This path must include the string `XXXXXX` in the file base name. | +bytes | `[Byte]` | The bytes to write to the file. | + +**Return:** The path of the newly created unique file. + + +**Example:** +```tomo +>> created := (./file-XXXXXX.txt).write_unique_bytes([1, 2, 3]) += (./file-27QHtq.txt) +>> created.read() += [1, 2, 3] +created.remove() + +``` diff --git a/api/paths.yaml b/api/paths.yaml new file mode 100644 index 00000000..c8df3d7b --- /dev/null +++ b/api/paths.yaml @@ -0,0 +1,875 @@ +Path.accessed: + description: > + Gets the file access time of a file. + return: + type: 'Int64?' + description: > + A 64-bit unix epoch timestamp representing when the file or directory was last + accessed, or `none` if no such file or directory exists. + args: + path: + type: 'Path' + description: > + The path of the file whose access time you want. + follow_symlinks: + type: 'Bool' + default: 'yes' + description: > + Whether to follow symbolic links. + example: | + >> (./file.txt).accessed() + = 1704221100? + >> (./not-a-file).accessed() + = none + +Path.append: + description: > + Appends the given text to the file at the specified path, creating the file if + it doesn't already exist. Failure to write will result in a runtime error. + return: + type: 'Void' + description: > + Nothing. + args: + path: + type: 'Path' + description: > + The path of the file to append to. + text: + type: 'Text' + description: > + The text to append to the file. + permissions: + type: 'Int32' + default: 'Int32(0o644)' + description: > + The permissions to set on the file if it is being created. + example: | + (./log.txt).append("extra line$(\n)") + +Path.append_bytes: + description: > + Appends the given bytes to the file at the specified path, creating the file if + it doesn't already exist. Failure to write will result in a runtime error. + return: + type: 'Void' + description: > + Nothing. + args: + path: + type: 'Path' + description: > + The path of the file to append to. + bytes: + type: '[Byte]' + description: > + The bytes to append to the file. + permissions: + type: 'Int32' + default: 'Int32(0o644)' + description: > + The permissions to set on the file if it is being created. + example: | + (./log.txt).append_bytes([104, 105]) + +Path.base_name: + description: > + Returns the base name of the file or directory at the specified path. + return: + type: 'Text' + description: > + The base name of the file or directory. + args: + path: + type: 'Path' + description: > + The path of the file or directory. + example: | + >> (./path/to/file.txt).base_name() + = "file.txt" + +Path.by_line: + description: > + Returns an iterator that can be used to iterate over a file one line at a time, + or returns a null value if the file could not be opened. + return: + type: 'func(->Text?)?' + description: > + An iterator that can be used to get lines from a file one at a time or a null + value if the file couldn't be read. + args: + path: + type: 'Path' + description: > + The path of the file. + example: | + # Safely handle file not being readable: + if lines := (./file.txt).by_line() + for line in lines + say(line.upper()) + else + say("Couldn't read file!") + + # Assume the file is readable and error if that's not the case: + for line in (/dev/stdin).by_line()! + say(line.upper()) + +Path.can_execute: + description: > + Returns whether or not a file can be executed by the current user/group. + return: + type: 'Bool' + description: > + `yes` if the file or directory exists and the current user has execute permissions, otherwise `no`. + args: + path: + type: 'Path' + description: > + The path of the file to check. + example: | + >> (/bin/sh).can_execute() + = yes + >> (/usr/include/stdlib.h).can_execute() + = no + >> (/non/existant/file).can_execute() + = no + +Path.can_read: + description: > + Returns whether or not a file can be read by the current user/group. + return: + type: 'Bool' + description: > + `yes` if the file or directory exists and the current user has read permissions, otherwise `no`. + args: + path: + type: 'Path' + description: > + The path of the file to check. + example: | + >> (/usr/include/stdlib.h).can_read() + = yes + >> (/etc/shadow).can_read() + = no + >> (/non/existant/file).can_read() + = no + +Path.can_write: + description: > + Returns whether or not a file can be written by the current user/group. + return: + type: 'Bool' + description: > + `yes` if the file or directory exists and the current user has write permissions, otherwise `no`. + args: + path: + type: 'Path' + description: > + The path of the file to check. + example: | + >> (/tmp).can_write() + = yes + >> (/etc/passwd).can_write() + = no + >> (/non/existant/file).can_write() + = no + +Path.changed: + description: > + Gets the file change time of a file. + note: > + This is the ["ctime"](https://en.wikipedia.org/wiki/Stat_(system_call)#ctime) of a file, + which is _not_ the file creation time. + return: + type: 'Int64?' + description: > + A 64-bit unix epoch timestamp representing when the file or directory was last + changed, or `none` if no such file or directory exists. + args: + path: + type: 'Path' + description: > + The path of the file whose change time you want. + follow_symlinks: + type: 'Bool' + default: 'yes' + description: > + Whether to follow symbolic links. + example: | + >> (./file.txt).changed() + = 1704221100? + >> (./not-a-file).changed() + = none + +Path.child: + description: > + Return a path that is a child of another path. + return: + type: '[Path]' + description: > + A new path representing the child. + args: + path: + type: 'Path' + description: > + The path of a directory. + child: + type: 'Text' + description: > + The name of a child file or directory. + example: | + >> (./directory).child("file.txt") + = (./directory/file.txt) + +Path.children: + description: > + Returns a list of children (files and directories) within the directory at the specified path. Optionally includes hidden files. + return: + type: '[Path]' + description: > + A list of paths for the children. + args: + path: + type: 'Path' + description: > + The path of the directory. + include_hidden: + default: 'no' + description: > + Whether to include hidden files, which start with a `.`. + example: | + >> (./directory).children(include_hidden=yes) + = [".git", "foo.txt"] + +Path.create_directory: + description: > + Creates a new directory at the specified path with the given permissions. If + any of the parent directories do not exist, they will be created as needed. + return: + type: 'Void' + description: > + Nothing. + args: + path: + type: 'Path' + description: > + The path of the directory to create. + permissions: + default: 'Int32(0o755)' + description: > + The permissions to set on the new directory. + example: | + (./new_directory).create_directory() + +Path.current_dir: + description: > + Creates a new directory at the specified path with the given permissions. If + any of the parent directories do not exist, they will be created as needed. + return: + type: 'Path' + description: > + The absolute path of the current directory. + args: + example: | + >> Path.current_dir() + = (/home/user/tomo) + +Path.exists: + description: > + Checks if a file or directory exists at the specified path. + return: + type: 'Bool' + description: > + `True` if the file or directory exists, `False` otherwise. + args: + path: + type: 'Path' + description: > + The path to check. + example: | + >> (/).exists() + = yes + +Path.expand_home: + description: > + For home-based paths (those starting with `~`), expand the path to replace the + tilde with and absolute path to the user's `$HOME` directory. + return: + type: 'Path' + description: > + If the path does not start with a `~`, then return it unmodified. Otherwise, + replace the `~` with an absolute path to the user's home directory. + args: + path: + type: 'Path' + description: > + The path to expand. + example: | + >> (~/foo).expand_home() # Assume current user is 'user' + = /home/user/foo + >> (/foo).expand_home() # No change + = /foo + +Path.extension: + description: > + Returns the file extension of the file at the specified path. Optionally returns the full extension. + return: + type: 'Text' + description: > + The file extension (not including the leading `.`) or an empty text if there is + no file extension. + args: + path: + type: 'Path' + description: > + The path of the file. + full: + type: 'Bool' + default: 'yes' + description: > + Whether to return everything after the first `.` in the base name, or + only the last part of the extension. + example: | + >> (./file.tar.gz).extension() + = "tar.gz" + >> (./file.tar.gz).extension(full=no) + = "gz" + >> (/foo).extension() + = "" + >> (./.git).extension() + = "" + +Path.files: + description: > + Returns a list of files within the directory at the specified path. Optionally includes hidden files. + return: + type: '[Path]' + description: > + A list of file paths. + args: + path: + type: 'Path' + description: > + The path of the directory. + include_hidden: + type: 'Bool' + default: 'no' + description: > + Whether to include hidden files. + example: | + >> (./directory).files(include_hidden=yes) + = [(./directory/file1.txt), (./directory/file2.txt)] + +Path.from_components: + description: > + Returns a path built from a list of path components. + return: + type: 'Path' + description: > + A path representing the given components. + args: + components: + type: '[Text]' + description: > + A list of path components. + example: | + >> Path.from_components(["/", "usr", "include"]) + = /usr/include + >> Path.from_components(["foo.txt"]) + = ./foo.txt + >> Path.from_components(["~", ".local"]) + = ~/.local + +Path.glob: + description: > + Perform a globbing operation and return a list of matching paths. Some glob + specific details: + + - The paths "." and ".." are *not* included in any globbing results. + + - Files or directories that begin with "." will not match `*`, but will match `.*`. + + - Globs do support `{a,b}` syntax for matching files that match any of several + choices of patterns. + + - The shell-style syntax `**` for matching subdirectories is not supported. + return: + type: '[Path]' + description: > + A list of file paths that match the glob. + args: + path: + type: 'Path' + description: > + The path of the directory which may contain special globbing characters + like `*`, `?`, or `{...}` + example: | + # Current directory includes: foo.txt, baz.txt, qux.jpg, .hidden + >> (./*).glob() + = [(./foo.txt), (./baz.txt), (./qux.jpg)] + + >> (./*.txt).glob() + = [(./foo.txt), (./baz.txt)] + + >> (./*.{txt,jpg}).glob() + = [(./foo.txt), (./baz.txt), (./qux.jpg)] + + >> (./.*).glob() + = [(./.hidden)] + + # Globs with no matches return an empty list: + >> (./*.xxx).glob() + = [] + +Path.group: + description: > + Get the owning group of a file or directory. + return: + type: 'Text?' + description: > + The name of the group which owns the file or directory, or `none` if the path does not exist. + args: + path: + type: 'Path' + description: > + The path whose owning group to get. + follow_symlinks: + type: 'Bool' + default: 'yes' + description: > + Whether to follow symbolic links. + example: | + >> (/bin).group() + = "root" + >> (/non/existent/file).group() + = none + +Path.is_directory: + description: > + Checks if the path represents a directory. Optionally follows symbolic links. + return: + type: 'Bool' + description: > + `True` if the path is a directory, `False` otherwise. + args: + path: + type: 'Path' + description: > + The path to check. + follow_symlinks: + default: 'yes' + description: > + Whether to follow symbolic links. + example: | + >> (./directory/).is_directory() + = yes + + >> (./file.txt).is_directory() + = no + +Path.is_file: + description: > + Checks if the path represents a file. Optionally follows symbolic links. + return: + type: 'Bool' + description: > + `True` if the path is a file, `False` otherwise. + args: + path: + type: 'Path' + description: > + The path to check. + follow_symlinks: + default: 'yes' + description: > + Whether to follow symbolic links. + example: | + >> (./file.txt).is_file() + = yes + + >> (./directory/).is_file() + = no + +Path.is_socket: + description: > + Checks if the path represents a socket. Optionally follows symbolic links. + return: + type: 'Bool' + description: > + `True` if the path is a socket, `False` otherwise. + args: + path: + type: 'Path' + description: > + The path to check. + follow_symlinks: + default: 'yes' + description: > + Whether to follow symbolic links. + example: | + >> (./socket).is_socket() + = yes + +Path.is_symlink: + description: > + Checks if the path represents a symbolic link. + return: + type: 'Bool' + description: > + `True` if the path is a symbolic link, `False` otherwise. + args: + path: + type: 'Path' + description: > + The path to check. + example: | + >> (./link).is_symlink() + = yes + +Path.modified: + description: > + Gets the file modification time of a file. + return: + type: 'Int64?' + description: > + A 64-bit unix epoch timestamp representing when the file or directory was last + modified, or `none` if no such file or directory exists. + args: + path: + type: 'Path' + description: > + The path of the file whose modification time you want. + follow_symlinks: + type: 'Bool' + default: 'yes' + description: > + Whether to follow symbolic links. + example: | + >> (./file.txt).modified() + = 1704221100? + >> (./not-a-file).modified() + = none + +Path.owner: + description: > + Get the owning user of a file or directory. + return: + type: 'Text?' + description: > + The name of the user who owns the file or directory, or `none` if the path does not exist. + args: + path: + type: 'Path' + description: > + The path whose owner to get. + follow_symlinks: + type: 'Bool' + default: 'yes' + description: > + Whether to follow symbolic links. + example: | + >> (/bin).owner() + = "root" + >> (/non/existent/file).owner() + = none + +Path.parent: + description: > + Returns the parent directory of the file or directory at the specified path. + return: + type: 'Path' + description: > + The path of the parent directory. + args: + path: + type: 'Path' + description: > + The path of the file or directory. + example: | + >> (./path/to/file.txt).parent() + = (./path/to/) + +Path.read: + description: > + Reads the contents of the file at the specified path or a null value if the + file could not be read. + return: + type: 'Text?' + description: > + The contents of the file. If the file could not be read, a null value will be + returned. If the file can be read, but is not valid UTF8 data, an error will be + raised. + args: + path: + type: 'Path' + description: > + The path of the file to read. + example: | + >> (./hello.txt).read() + = "Hello"? + + >> (./nosuchfile.xxx).read() + = none + +Path.read_bytes: + description: > + Reads the contents of the file at the specified path or a null value if the + file could not be read. + return: + type: '[Byte]?' + description: > + The byte contents of the file. If the file cannot be read, a null value will be + returned. + args: + path: + type: 'Path' + description: > + The path of the file to read. + limit: + type: 'Int?' + default: 'none' + description: > + A limit to how many bytes should be read. + example: | + >> (./hello.txt).read() + = [72, 101, 108, 108, 111]? + + >> (./nosuchfile.xxx).read() + = none + +Path.relative_to: + description: > + Returns the path relative to a given base path. By default, the base path is the current directory. + return: + type: 'Path' + description: > + The relative path. + args: + path: + type: 'Path' + description: > + The path to convert. + relative_to: + default: '(./)' + description: > + The base path for the relative path. + example: | + >> (./path/to/file.txt).relative(relative_to=(./path)) + = (./to/file.txt) + +Path.remove: + description: > + Removes the file or directory at the specified path. A runtime error is raised if something goes wrong. + return: + type: 'Void' + description: > + Nothing. + args: + path: + type: 'Path' + description: > + The path to remove. + ignore_missing: + default: 'no' + description: > + Whether to ignore errors if the file or directory does not exist. + example: | + (./file.txt).remove() + +Path.resolved: + description: > + Resolves the absolute path of the given path relative to a base path. By default, the base path is the current directory. + return: + type: 'Path' + description: > + The resolved absolute path. + args: + path: + type: 'Path' + description: > + The path to resolve. + relative_to: + default: '(./)' + description: > + The base path for resolution. + example: | + >> (~/foo).resolved() + = (/home/user/foo) + + >> (./path/to/file.txt).resolved(relative_to=(/foo)) + = (/foo/path/to/file.txt) + +Path.set_owner: + description: > + Set the owning user and/or group for a path. + return: + type: 'Void' + description: > + Nothing. If a path does not exist, a failure will be raised. + args: + path: + type: 'Path' + description: > + The path to change the permissions for. + owner: + type: 'Text?' + default: 'none' + description: > + If non-none, the new user to assign to be the owner of the file. + group: + type: 'Text?' + default: 'none' + description: > + If non-none, the new group to assign to be the owner of the file. + follow_symlinks: + type: 'Bool' + default: 'yes' + description: > + Whether to follow symbolic links. + example: | + (./file.txt).set_owner(owner="root", group="wheel") + +Path.subdirectories: + description: > + Returns a list of subdirectories within the directory at the specified path. Optionally includes hidden subdirectories. + return: + type: '[Path]' + description: > + A list of subdirectory paths. + args: + path: + type: 'Path' + description: > + The path of the directory. + include_hidden: + default: 'no' + description: > + Whether to include hidden subdirectories. + example: | + >> (./directory).subdirectories() + = [(./directory/subdir1), (./directory/subdir2)] + + >> (./directory).subdirectories(include_hidden=yes) + = [(./directory/.git), (./directory/subdir1), (./directory/subdir2)] + +Path.unique_directory: + description: > + Generates a unique directory path based on the given path. Useful for creating temporary directories. + return: + type: 'Path' + description: > + A unique directory path after creating the directory. + args: + path: + type: 'Path' + description: > + The base path for generating the unique directory. The last six letters of this path must be `XXXXXX`. + example: | + >> created := (/tmp/my-dir.XXXXXX).unique_directory() + = (/tmp/my-dir-AwoxbM/) + >> created.is_directory() + = yes + created.remove() + +Path.write: + description: > + Writes the given text to the file at the specified path, creating the file if + it doesn't already exist. Sets the file permissions as specified. If the file + writing cannot be successfully completed, a runtime error is raised. + return: + type: 'Void' + description: > + Nothing. + args: + path: + type: 'Path' + description: > + The path of the file to write to. + text: + type: 'Text' + description: > + The text to write to the file. + permissions: + default: 'Int32(0o644)' + description: > + The permissions to set on the file if it is created. + example: | + (./file.txt).write("Hello, world!") + +Path.write_bytes: + description: > + Writes the given bytes to the file at the specified path, creating the file if + it doesn't already exist. Sets the file permissions as specified. If the file + writing cannot be successfully completed, a runtime error is raised. + return: + type: 'Void' + description: > + Nothing. + args: + path: + type: 'Path' + description: > + The path of the file to write to. + bytes: + type: '[Byte]' + description: > + A list of bytes to write to the file. + permissions: + default: 'Int32(0o644)' + description: > + The permissions to set on the file if it is created. + example: | + (./file.txt).write_bytes([104, 105]) + +Path.write_unique: + description: > + Writes the given text to a unique file path based on the specified path. The + file is created if it doesn't exist. This is useful for creating temporary + files. + return: + type: 'Path' + description: > + The path of the newly created unique file. + args: + path: + type: 'Path' + description: > + The base path for generating the unique file. This path must include + the string `XXXXXX` in the file base name. + text: + type: 'Text' + description: > + The text to write to the file. + example: | + >> created := (./file-XXXXXX.txt).write_unique("Hello, world!") + = (./file-27QHtq.txt) + >> created.read() + = "Hello, world!" + created.remove() + +Path.write_unique_bytes: + description: > + Writes the given bytes to a unique file path based on the specified path. The + file is created if it doesn't exist. This is useful for creating temporary + files. + return: + type: 'Path' + description: > + The path of the newly created unique file. + args: + path: + type: 'Path' + description: > + The base path for generating the unique file. This path must include + the string `XXXXXX` in the file base name. + bytes: + type: '[Byte]' + description: > + The bytes to write to the file. + example: | + >> created := (./file-XXXXXX.txt).write_unique_bytes([1, 2, 3]) + = (./file-27QHtq.txt) + >> created.read() + = [1, 2, 3] + created.remove() + diff --git a/api/sets.md b/api/sets.md new file mode 100644 index 00000000..74016079 --- /dev/null +++ b/api/sets.md @@ -0,0 +1,243 @@ +% API + +# Builtins + +# Set +## Set.add + +```tomo +Set.add : func(set: |T|, item: T -> Void) +``` + +Adds an item to the set. + +Argument | Type | Description | Default +---------|------|-------------|--------- +set | `|T|` | The mutable reference to the set. | +item | `T` | The item to add to the set. | + +**Return:** Nothing. + + +**Example:** +```tomo +>> nums.add(42) + +``` +## Set.add_all + +```tomo +Set.add_all : func(set: @|T|, items: [T] -> Void) +``` + +Adds multiple items to the set. + +Argument | Type | Description | Default +---------|------|-------------|--------- +set | `@|T|` | The mutable reference to the set. | +items | `[T]` | The list of items to add to the set. | + +**Return:** Nothing. + + +**Example:** +```tomo +>> nums.add_all([1, 2, 3]) + +``` +## Set.clear + +```tomo +Set.clear : func(set: @|T| -> Void) +``` + +Removes all items from the set. + +Argument | Type | Description | Default +---------|------|-------------|--------- +set | `@|T|` | The mutable reference to the set. | + +**Return:** Nothing. + + +**Example:** +```tomo +>> nums.clear() + +``` +## Set.has + +```tomo +Set.has : func(set: |T|, item: T -> Bool) +``` + +Checks if the set contains a specified item. + +Argument | Type | Description | Default +---------|------|-------------|--------- +set | `|T|` | The set to check. | +item | `T` | The item to check for presence. | + +**Return:** `yes` if the item is present, `no` otherwise. + + +**Example:** +```tomo +>> |10, 20|.has(20) += yes + +``` +## Set.is_subset_of + +```tomo +Set.is_subset_of : func(set: |T|, other: |T|, strict: Bool = no -> Bool) +``` + +Checks if the set is a subset of another set. + +Argument | Type | Description | Default +---------|------|-------------|--------- +set | `|T|` | The set to check. | +other | `|T|` | The set to compare against. | +strict | `Bool` | If `yes`, checks if the set is a strict subset (does not equal the other set). | **Default:** `no` + +**Return:** `yes` if the set is a subset of the other set (strictly or not), `no` otherwise. + + +**Example:** +```tomo +>> |1, 2|.is_subset_of(|1, 2, 3|) += yes + +``` +## Set.is_superset_of + +```tomo +Set.is_superset_of : func(set: |T|, other: |T|, strict: Bool = no -> Bool) +``` + +Checks if the set is a superset of another set. + +Argument | Type | Description | Default +---------|------|-------------|--------- +set | `|T|` | The set to check. | +other | `|T|` | The set to compare against. | +strict | `Bool` | If `yes`, checks if the set is a strict superset (does not equal the other set). | **Default:** `no` + +**Return:** `yes` if the set is a superset of the other set (strictly or not), `no` otherwise. + + +**Example:** +```tomo +>> |1, 2, 3|.is_superset_of(|1, 2|) += yes + +``` +## Set.overlap + +```tomo +Set.overlap : func(set: |T|, other: |T| -> |T|) +``` + +Creates a new set with items that are in both the original set and another set. + +Argument | Type | Description | Default +---------|------|-------------|--------- +set | `|T|` | The original set. | +other | `|T|` | The set to intersect with. | + +**Return:** A new set containing only items present in both sets. + + +**Example:** +```tomo +>> |1, 2|.overlap(|2, 3|) += |2| + +``` +## Set.remove + +```tomo +Set.remove : func(set: @|T|, item: T -> Void) +``` + +Removes an item from the set. + +Argument | Type | Description | Default +---------|------|-------------|--------- +set | `@|T|` | The mutable reference to the set. | +item | `T` | The item to remove from the set. | + +**Return:** Nothing. + + +**Example:** +```tomo +>> nums.remove(42) + +``` +## Set.remove_all + +```tomo +Set.remove_all : func(set: @|T|, items: [T] -> Void) +``` + +Removes multiple items from the set. + +Argument | Type | Description | Default +---------|------|-------------|--------- +set | `@|T|` | The mutable reference to the set. | +items | `[T]` | The list of items to remove from the set. | + +**Return:** Nothing. + + +**Example:** +```tomo +>> nums.remove_all([1, 2, 3]) + +``` +## Set.with + +```tomo +Set.with : func(set: |T|, other: |T| -> |T|) +``` + +Creates a new set that is the union of the original set and another set. + +Argument | Type | Description | Default +---------|------|-------------|--------- +set | `|T|` | The original set. | +other | `|T|` | The set to union with. | + +**Return:** A new set containing all items from both sets. + + +**Example:** +```tomo +>> |1, 2|.with(|2, 3|) += |1, 2, 3| + +``` +## Set.without + +```tomo +Set.without : func(set: |T|, other: |T| -> |T|) +``` + +Creates a new set with items from the original set but without items from another set. + +Argument | Type | Description | Default +---------|------|-------------|--------- +set | `|T|` | The original set. | +other | `|T|` | The set of items to remove from the original set. | + +**Return:** A new set containing items from the original set excluding those in the other set. + + +**Example:** +```tomo +>> |1, 2|.without(|2, 3|) += |1| + +``` diff --git a/api/sets.yaml b/api/sets.yaml new file mode 100644 index 00000000..19d30f1d --- /dev/null +++ b/api/sets.yaml @@ -0,0 +1,221 @@ +Set.add: + description: > + Adds an item to the set. + return: + type: 'Void' + description: > + Nothing. + args: + set: + type: '|T|' + description: > + The mutable reference to the set. + item: + type: 'T' + description: > + The item to add to the set. + example: | + >> nums.add(42) + +Set.add_all: + description: > + Adds multiple items to the set. + return: + type: 'Void' + description: > + Nothing. + args: + set: + type: '@|T|' + description: > + The mutable reference to the set. + items: + type: '[T]' + description: > + The list of items to add to the set. + example: | + >> nums.add_all([1, 2, 3]) + +Set.clear: + description: > + Removes all items from the set. + return: + type: 'Void' + description: > + Nothing. + args: + set: + type: '@|T|' + description: > + The mutable reference to the set. + example: | + >> nums.clear() + +Set.has: + description: > + Checks if the set contains a specified item. + return: + type: 'Bool' + description: > + `yes` if the item is present, `no` otherwise. + args: + set: + type: '|T|' + description: > + The set to check. + item: + type: 'T' + description: > + The item to check for presence. + example: | + >> |10, 20|.has(20) + = yes + +Set.is_subset_of: + description: > + Checks if the set is a subset of another set. + return: + type: 'Bool' + description: > + `yes` if the set is a subset of the other set (strictly or not), `no` otherwise. + args: + set: + type: '|T|' + description: > + The set to check. + other: + type: '|T|' + description: > + The set to compare against. + strict: + type: 'Bool' + default: 'no' + description: > + If `yes`, checks if the set is a strict subset (does not equal the other set). + example: | + >> |1, 2|.is_subset_of(|1, 2, 3|) + = yes + +Set.is_superset_of: + description: > + Checks if the set is a superset of another set. + return: + type: 'Bool' + description: > + `yes` if the set is a superset of the other set (strictly or not), `no` otherwise. + args: + set: + type: '|T|' + description: > + The set to check. + other: + type: '|T|' + description: > + The set to compare against. + strict: + type: 'Bool' + default: 'no' + description: > + If `yes`, checks if the set is a strict superset (does not equal the other set). + example: | + >> |1, 2, 3|.is_superset_of(|1, 2|) + = yes + +Set.overlap: + description: > + Creates a new set with items that are in both the original set and another set. + return: + type: '|T|' + description: > + A new set containing only items present in both sets. + args: + set: + type: '|T|' + description: > + The original set. + other: + type: '|T|' + description: > + The set to intersect with. + example: | + >> |1, 2|.overlap(|2, 3|) + = |2| + +Set.remove: + description: > + Removes an item from the set. + return: + type: 'Void' + description: > + Nothing. + args: + set: + type: '@|T|' + description: > + The mutable reference to the set. + item: + type: 'T' + description: > + The item to remove from the set. + example: | + >> nums.remove(42) + +Set.remove_all: + description: > + Removes multiple items from the set. + return: + type: 'Void' + description: > + Nothing. + args: + set: + type: '@|T|' + description: > + The mutable reference to the set. + items: + type: '[T]' + description: > + The list of items to remove from the set. + example: | + >> nums.remove_all([1, 2, 3]) + +Set.with: + description: > + Creates a new set that is the union of the original set and another set. + return: + type: '|T|' + description: > + A new set containing all items from both sets. + args: + set: + type: '|T|' + description: > + The original set. + other: + type: '|T|' + description: > + The set to union with. + example: | + >> |1, 2|.with(|2, 3|) + = |1, 2, 3| + +Set.without: + description: > + Creates a new set with items from the original set but without items from another set. + return: + type: '|T|' + description: > + A new set containing items from the original set excluding those in the other set. + args: + set: + type: '|T|' + description: > + The original set. + other: + type: '|T|' + description: > + The set of items to remove from the original set. + example: | + >> |1, 2|.without(|2, 3|) + = |1| + diff --git a/api/tables.md b/api/tables.md new file mode 100644 index 00000000..28c5c202 --- /dev/null +++ b/api/tables.md @@ -0,0 +1,164 @@ +% API + +# Builtins + +# Table +## Table.clear + +```tomo +Table.clear : func(t: &{K=V} -> Void) +``` + +Removes all key-value pairs from the table. + +Argument | Type | Description | Default +---------|------|-------------|--------- +t | `&{K=V}` | The reference to the table. | + +**Return:** Nothing. + + +**Example:** +```tomo +>> t.clear() + +``` +## Table.get + +```tomo +Table.get : func(t: {K=V}, key: K -> V?) +``` + +Retrieves the value associated with a key, or returns `none` if the key is not present. **Note:** default values for the table are ignored. + +Argument | Type | Description | Default +---------|------|-------------|--------- +t | `{K=V}` | The table. | +key | `K` | The key whose associated value is to be retrieved. | + +**Return:** The value associated with the key or `none` if the key is not found. + + +**Example:** +```tomo +>> t := {"A"=1, "B"=2} +>> t.get("A") += 1? + +>> t.get("????") += none + +>> t.get("A")! += 1 + +>> t.get("????") or 0 += 0 + +``` +## Table.get_or_set + +```tomo +Table.get_or_set : func(t: &{K=V}, key: K, default: V -> V?) +``` + +If the given key is in the table, return the associated value. Otherwise, insert the given default value into the table and return it. + +If no default value is provided explicitly, but the table has a default value associated with it, the table's default value will be used. +The default value is only evaluated if the key is missing. + +Argument | Type | Description | Default +---------|------|-------------|--------- +t | `&{K=V}` | The table. | +key | `K` | The key whose associated value is to be retrieved. | +default | `V` | The default value to insert and return if the key is not present in the table. | + +**Return:** Either the value associated with the key (if present) or the default value. The table will be mutated if the key is not already present. + + +**Example:** +```tomo +>> t := &{"A"=@[1, 2, 3]; default=@[]} +>> t.get_or_set("A").insert(4) +>> t.get_or_set("B").insert(99) +>> t += &{"A"=@[1, 2, 3, 4], "B"=@[99]} + +>> t.get_or_set("C", @[0, 0, 0]) += @[0, 0, 0] +>> t += &{"A"=@[1, 2, 3, 4], "B"=@[99], "C"=@[0, 0, 0]} + +``` +## Table.has + +```tomo +Table.has : func(t: {K=V}, key: K -> Bool) +``` + +Checks if the table contains a specified key. + +Argument | Type | Description | Default +---------|------|-------------|--------- +t | `{K=V}` | The table. | +key | `K` | The key to check for presence. | + +**Return:** `yes` if the key is present, `no` otherwise. + + +**Example:** +```tomo +>> {"A"=1, "B"=2}.has("A") += yes +>> {"A"=1, "B"=2}.has("xxx") += no + +``` +## Table.remove + +```tomo +Table.remove : func(t: {K=V}, key: K -> Void) +``` + +Removes the key-value pair associated with a specified key. + +Argument | Type | Description | Default +---------|------|-------------|--------- +t | `{K=V}` | The reference to the table. | +key | `K` | The key of the key-value pair to remove. | + +**Return:** Nothing. + + +**Example:** +```tomo +t := {"A"=1, "B"=2} +t.remove("A") +>> t += {"B"=2} + +``` +## Table.set + +```tomo +Table.set : func(t: {K=V}, key: K, value: V -> Void) +``` + +Sets or updates the value associated with a specified key. + +Argument | Type | Description | Default +---------|------|-------------|--------- +t | `{K=V}` | The reference to the table. | +key | `K` | The key to set or update. | +value | `V` | The value to associate with the key. | + +**Return:** Nothing. + + +**Example:** +```tomo +t := {"A"=1, "B"=2} +t.set("C", 3) +>> t += {"A"=1, "B"=2, "C"=3} + +``` diff --git a/api/tables.yaml b/api/tables.yaml new file mode 100644 index 00000000..c1cdd53d --- /dev/null +++ b/api/tables.yaml @@ -0,0 +1,155 @@ +Table.clear: + description: > + Removes all key-value pairs from the table. + return: + type: 'Void' + description: > + Nothing. + args: + t: + type: '&{K=V}' + description: > + The reference to the table. + example: | + >> t.clear() + +Table.get: + description: > + Retrieves the value associated with a key, or returns `none` if the key is not present. + **Note:** default values for the table are ignored. + return: + type: 'V?' + description: > + The value associated with the key or `none` if the key is not found. + args: + t: + type: '{K=V}' + description: > + The table. + key: + type: 'K' + description: > + The key whose associated value is to be retrieved. + example: | + >> t := {"A"=1, "B"=2} + >> t.get("A") + = 1? + + >> t.get("????") + = none + + >> t.get("A")! + = 1 + + >> t.get("????") or 0 + = 0 + +Table.get_or_set: + description: > + If the given key is in the table, return the associated value. Otherwise, + insert the given default value into the table and return it. + note: > + If no default value is provided explicitly, but the table has a + default value associated with it, the table's default value will be used. + + The default value is only evaluated if the key is missing. + return: + type: 'V?' + description: > + Either the value associated with the key (if present) or the default value. The + table will be mutated if the key is not already present. + args: + t: + type: "&{K=V}" + description: > + The table. + key: + type: "K" + description: > + The key whose associated value is to be retrieved. + default: + type: "V" + description: > + The default value to insert and return if the key is not present in the table. + example: | + >> t := &{"A"=@[1, 2, 3]; default=@[]} + >> t.get_or_set("A").insert(4) + >> t.get_or_set("B").insert(99) + >> t + = &{"A"=@[1, 2, 3, 4], "B"=@[99]} + + >> t.get_or_set("C", @[0, 0, 0]) + = @[0, 0, 0] + >> t + = &{"A"=@[1, 2, 3, 4], "B"=@[99], "C"=@[0, 0, 0]} + +Table.has: + description: > + Checks if the table contains a specified key. + return: + type: 'Bool' + description: > + `yes` if the key is present, `no` otherwise. + args: + t: + type: '{K=V}' + description: > + The table. + key: + type: 'K' + description: > + The key to check for presence. + example: | + >> {"A"=1, "B"=2}.has("A") + = yes + >> {"A"=1, "B"=2}.has("xxx") + = no + +Table.remove: + description: > + Removes the key-value pair associated with a specified key. + return: + type: 'Void' + description: > + Nothing. + args: + t: + type: '{K=V}' + description: > + The reference to the table. + key: + type: 'K' + description: > + The key of the key-value pair to remove. + example: | + t := {"A"=1, "B"=2} + t.remove("A") + >> t + = {"B"=2} + +Table.set: + description: > + Sets or updates the value associated with a specified key. + return: + type: 'Void' + description: > + Nothing. + args: + t: + type: '{K=V}' + description: > + The reference to the table. + key: + type: 'K' + description: > + The key to set or update. + value: + type: 'V' + description: > + The value to associate with the key. + example: | + t := {"A"=1, "B"=2} + t.set("C", 3) + >> t + = {"A"=1, "B"=2, "C"=3} + diff --git a/api/text.md b/api/text.md new file mode 100644 index 00000000..e542ec90 --- /dev/null +++ b/api/text.md @@ -0,0 +1,923 @@ +% API + +# Builtins + +# Text +## Text.as_c_string + +```tomo +Text.as_c_string : func(text: Text -> CString) +``` + +Converts a `Text` value to a C-style string. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be converted to a C-style string. | + +**Return:** A C-style string (`CString`) representing the text. + + +**Example:** +```tomo +>> "Hello".as_c_string() += CString("Hello") + +``` +## Text.at + +```tomo +Text.at : func(text: Text, index: Int -> Text) +``` + +Get the graphical cluster at a given index. This is similar to `str[i]` with ASCII text, but has more correct behavior for unicode text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text from which to get a cluster. | +index | `Int` | The index of the graphical cluster (1-indexed). | + +**Return:** A `Text` with the single graphical cluster at the given index. Note: negative indices are counted from the back of the text, so `-1` means the last cluster, `-2` means the second-to-last, and so on. + + +**Example:** +```tomo +>> "Amélie".at(3) += "é" + +``` +## Text.by_line + +```tomo +Text.by_line : func(text: Text -> func(->Text?)) +``` + +Returns an iterator function that can be used to iterate over the lines in a text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be iterated over, line by line. | + +**Return:** An iterator function that returns one line at a time, until it runs out and returns `none`. **Note:** this function ignores a trailing newline if there is one. If you don't want this behavior, use `text.by_split($/{1 nl}/)` instead. + + +**Example:** +```tomo +text := " +line one +line two +" +for line in text.by_line() +# Prints: "line one" then "line two": +say(line) + +``` +## Text.by_split + +```tomo +Text.by_split : func(text: Text, delimiter: Text = "" -> func(->Text?)) +``` + +Returns an iterator function that can be used to iterate over text separated by a delimiter. **Note:** to split based on a set of delimiters, use [`by_split_any()`](#by_split_any). + +If an empty text is given as the delimiter, then each split will be the graphical clusters of the text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be iterated over in delimited chunks. | +delimiter | `Text` | An exact delimiter to use for splitting the text. | **Default:** `""` + +**Return:** An iterator function that returns one chunk of text at a time, separated by the given delimiter, until it runs out and returns `none`. **Note:** using an empty delimiter (the default) will iterate over single grapheme clusters in the text. + + +**Example:** +```tomo +text := "one,two,three" +for chunk in text.by_split(",") +# Prints: "one" then "two" then "three": +say(chunk) + +``` +## Text.by_split_any + +```tomo +Text.by_split_any : func(text: Text, delimiters: Text = " $\t\r\n" -> func(->Text?)) +``` + +Returns an iterator function that can be used to iterate over text separated by one or more characters (grapheme clusters) from a given text of delimiters. **Note:** to split based on an exact delimiter, use [`by_split()`](#by_split). + +Splitting will occur on every place where one or more of the grapheme clusters in `delimiters` occurs. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be iterated over in delimited chunks. | +delimiters | `Text` | Grapheme clusters to use for splitting the text. | **Default:** `" $\t\r\n"` + +**Return:** An iterator function that returns one chunk of text at a time, separated by the given delimiter characters, until it runs out and returns `none`. + + +**Example:** +```tomo +text := "one,two,;,three" +for chunk in text.by_split_any(",;") +# Prints: "one" then "two" then "three": +say(chunk) + +``` +## Text.bytes + +```tomo +Text.bytes : func(text: Text -> [Byte]) +``` + +Converts a `Text` value to a list of bytes representing a UTF8 encoding of the text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be converted to UTF8 bytes. | + +**Return:** A list of bytes (`[Byte]`) representing the text in UTF8 encoding. + + +**Example:** +```tomo +>> "Amélie".bytes() += [65, 109, 195, 169, 108, 105, 101] + +``` +## Text.caseless_equals + +```tomo +Text.caseless_equals : func(a: Text, b: Text, language: Text = "C" -> Bool) +``` + +Checks whether two texts are equal, ignoring the casing of the letters (i.e. case-insensitive comparison). + +Argument | Type | Description | Default +---------|------|-------------|--------- +a | `Text` | The first text to compare case-insensitively. | +b | `Text` | The second text to compare case-insensitively. | +language | `Text` | The ISO 639 language code for which casing rules to use. | **Default:** `"C"` + +**Return:** `yes` if `a` and `b` are equal to each other, ignoring casing, otherwise `no`. + + +**Example:** +```tomo +>> "A".caseless_equals("a") += yes + +# Turkish lowercase "I" is "ı" (dotless I), not "i" +>> "I".caseless_equals("i", language="tr_TR") += no + +``` +## Text.codepoint_names + +```tomo +Text.codepoint_names : func(text: Text -> [Text]) +``` + +Returns a list of the names of each codepoint in the text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text from which to extract codepoint names. | + +**Return:** A list of codepoint names (`[Text]`). + + +**Example:** +```tomo +>> "Amélie".codepoint_names() += ["LATIN CAPITAL LETTER A", "LATIN SMALL LETTER M", "LATIN SMALL LETTER E WITH ACUTE", "LATIN SMALL LETTER L", "LATIN SMALL LETTER I", "LATIN SMALL LETTER E"] + +``` +## Text.ends_with + +```tomo +Text.ends_with : func(text: Text, suffix: Text -> Bool) +``` + +Checks if the `Text` ends with a literal suffix text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be searched. | +suffix | `Text` | The literal suffix text to check for. | + +**Return:** `yes` if the text has the target, `no` otherwise. + + +**Example:** +```tomo +>> "hello world".ends_with("world") += yes + +``` +## Text.from + +```tomo +Text.from : func(text: Text, first: Int -> Text) +``` + +Get a slice of the text, starting at the given position. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be sliced. | +first | `Int` | The index to begin the slice. | + +**Return:** The text from the given grapheme cluster to the end of the text. Note: a negative index counts backwards from the end of the text, so `-1` refers to the last cluster, `-2` the second-to-last, etc. Slice ranges will be truncated to the length of the text. + + +**Example:** +```tomo +>> "hello".from(2) += "ello" + +>> "hello".from(-2) += "lo" + +``` +## Text.from_bytes + +```tomo +Text.from_bytes : func(bytes: [Byte] -> [Text]) +``` + +Returns text that has been constructed from the given UTF8 bytes. Note: the text will be normalized, so the resulting text's UTF8 bytes may not exactly match the input. + +Argument | Type | Description | Default +---------|------|-------------|--------- +bytes | `[Byte]` | The UTF-8 bytes of the desired text. | + +**Return:** A new text based on the input UTF8 bytes after normalization has been applied. + + +**Example:** +```tomo +>> Text.from_bytes([195, 133, 107, 101]) += "Åke" + +``` +## Text.from_c_string + +```tomo +Text.from_c_string : func(str: CString -> Text) +``` + +Converts a C-style string to a `Text` value. + +Argument | Type | Description | Default +---------|------|-------------|--------- +str | `CString` | The C-style string to be converted. | + +**Return:** A `Text` value representing the C-style string. + + +**Example:** +```tomo +>> Text.from_c_string(CString("Hello")) += "Hello" + +``` +## Text.from_codepoint_names + +```tomo +Text.from_codepoint_names : func(codepoint_names: [Text] -> [Text]) +``` + +Returns text that has the given codepoint names (according to the Unicode specification) as its codepoints. Note: the text will be normalized, so the resulting text's codepoints may not exactly match the input codepoints. + +Argument | Type | Description | Default +---------|------|-------------|--------- +codepoint_names | `[Text]` | The names of each codepoint in the desired text (case-insentive). | + +**Return:** A new text with the specified codepoints after normalization has been applied. Any invalid names are ignored. + + +**Example:** +```tomo +>> Text.from_codepoint_names([ +"LATIN CAPITAL LETTER A WITH RING ABOVE", +"LATIN SMALL LETTER K", +"LATIN SMALL LETTER E", +] += "Åke" + +``` +## Text.from_codepoints + +```tomo +Text.from_codepoints : func(codepoints: [Int32] -> [Text]) +``` + +Returns text that has been constructed from the given UTF32 codepoints. Note: the text will be normalized, so the resulting text's codepoints may not exactly match the input codepoints. + +Argument | Type | Description | Default +---------|------|-------------|--------- +codepoints | `[Int32]` | The UTF32 codepoints in the desired text. | + +**Return:** A new text with the specified codepoints after normalization has been applied. + + +**Example:** +```tomo +>> Text.from_codepoints([197, 107, 101]) += "Åke" + +``` +## Text.has + +```tomo +Text.has : func(text: Text, target: Text -> Bool) +``` + +Checks if the `Text` contains some target text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be searched. | +target | `Text` | The text to search for. | + +**Return:** `yes` if the target text is found, `no` otherwise. + + +**Example:** +```tomo +>> "hello world".has("wo") += yes +>> "hello world".has("xxx") += no + +``` +## Text.join + +```tomo +Text.join : func(glue: Text, pieces: [Text] -> Text) +``` + +Joins a list of text pieces with a specified glue. + +Argument | Type | Description | Default +---------|------|-------------|--------- +glue | `Text` | The text used to join the pieces. | +pieces | `[Text]` | The list of text pieces to be joined. | + +**Return:** A single `Text` value with the pieces joined by the glue. + + +**Example:** +```tomo +>> ", ".join(["one", "two", "three"]) += "one, two, three" + +``` +## Text.left_pad + +```tomo +Text.left_pad : func(text: Text, width: Int, pad: Text = " ", language: Text = "C" -> Text) +``` + +Pad some text on the left side so it reaches a target width. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to pad. | +width | `Int` | The target width. | +pad | `Text` | The padding text. | **Default:** `" "` +language | `Text` | The ISO 639 language code for which character width to use. | **Default:** `"C"` + +**Return:** Text with length at least `width`, with extra padding on the left as needed. If `pad` has length greater than 1, it may be partially repeated to reach the exact desired length. + + +**Example:** +```tomo +>> "x".left_pad(5) += " x" +>> "x".left_pad(5, "ABC") += "ABCAx" + +``` +## Text.lines + +```tomo +Text.lines : func(text: Text -> [Text]) +``` + +Splits the text into a list of lines of text, preserving blank lines, ignoring trailing newlines, and handling `\r\n` the same as `\n`. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be split into lines. | + +**Return:** A list of substrings resulting from the split. + + +**Example:** +```tomo +>> "one\ntwo\nthree".lines() += ["one", "two", "three"] +>> "one\ntwo\nthree\n".lines() += ["one", "two", "three"] +>> "one\ntwo\nthree\n\n".lines() += ["one", "two", "three", ""] +>> "one\r\ntwo\r\nthree\r\n".lines() += ["one", "two", "three"] +>> "".lines() += [] + +``` +## Text.lower + +```tomo +Text.lower : func(text: Text, language: Text = "C" -> Text) +``` + +Converts all characters in the text to lowercase. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be converted to lowercase. | +language | `Text` | The ISO 639 language code for which casing rules to use. | **Default:** `"C"` + +**Return:** The lowercase version of the text. + + +**Example:** +```tomo +>> "AMÉLIE".lower() += "amélie" + +>> "I".lower(language="tr_TR") +>> "ı" + +``` +## Text.middle_pad + +```tomo +Text.middle_pad : func(text: Text, width: Int, pad: Text = " ", language: Text = "C" -> Text) +``` + +Pad some text on the left and right side so it reaches a target width. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to pad. | +width | `Int` | The target width. | +pad | `Text` | The padding text. | **Default:** `" "` +language | `Text` | The ISO 639 language code for which character width to use. | **Default:** `"C"` + +**Return:** Text with length at least `width`, with extra padding on the left and right as needed. If `pad` has length greater than 1, it may be partially repeated to reach the exact desired length. + + +**Example:** +```tomo +>> "x".middle_pad(6) += " x " +>> "x".middle_pad(10, "ABC") += "ABCAxABCAB" + +``` +## Text.quoted + +```tomo +Text.quoted : func(text: Text, color: Bool = no, quotation_mark: Text = `"` -> Text) +``` + +Formats the text with quotation marks and escapes. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be quoted. | +color | `Bool` | Whether to add color formatting. | **Default:** `no` +quotation_mark | `Text` | The quotation mark to use. | **Default:** ``"`` + +**Return:** The text formatted as a quoted text. + + +**Example:** +```tomo +>> "one\ntwo".quoted() += "\"one\\ntwo\"" + +``` +## Text.repeat + +```tomo +Text.repeat : func(text: Text, count: Int -> Text) +``` + +Repeat some text multiple times. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to repeat. | +count | `Int` | The number of times to repeat it. (Negative numbers are equivalent to zero). | + +**Return:** The text repeated the given number of times. + + +**Example:** +```tomo +>> "Abc".repeat(3) += "AbcAbcAbc" + +``` +## Text.replace + +```tomo +Text.replace : func(text: Text, target: Text, replacement: Text -> Text) +``` + +Replaces occurrences of a target text with a replacement text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text in which to perform replacements. | +target | `Text` | The target text to be replaced. | +replacement | `Text` | The text to replace the target with. | + +**Return:** The text with occurrences of the target replaced. + + +**Example:** +```tomo +>> "Hello world".replace("world", "there") += "Hello there" + +``` +## Text.reversed + +```tomo +Text.reversed : func(text: Text -> Text) +``` + +Return a text that has the grapheme clusters in reverse order. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to reverse. | + +**Return:** A reversed version of the text. + + +**Example:** +```tomo +>> "Abc".reversed() += "cbA" + +``` +## Text.right_pad + +```tomo +Text.right_pad : func(text: Text, width: Int, pad: Text = " ", language: Text = "C" -> Text) +``` + +Pad some text on the right side so it reaches a target width. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to pad. | +width | `Int` | The target width. | +pad | `Text` | The padding text. | **Default:** `" "` +language | `Text` | The ISO 639 language code for which character width to use. | **Default:** `"C"` + +**Return:** Text with length at least `width`, with extra padding on the right as needed. If `pad` has length greater than 1, it may be partially repeated to reach the exact desired length. + + +**Example:** +```tomo +>> "x".right_pad(5) += "x " +>> "x".right_pad(5, "ABC") += "xABCA" + +``` +## Text.slice + +```tomo +Text.slice : func(text: Text, from: Int = 1, to: Int = -1 -> Text) +``` + +Get a slice of the text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be sliced. | +from | `Int` | The index of the first grapheme cluster to include (1-indexed). | **Default:** `1` +to | `Int` | The index of the last grapheme cluster to include (1-indexed). | **Default:** `-1` + +**Return:** The text that spans the given grapheme cluster indices. Note: a negative index counts backwards from the end of the text, so `-1` refers to the last cluster, `-2` the second-to-last, etc. Slice ranges will be truncated to the length of the text. + + +**Example:** +```tomo +>> "hello".slice(2, 3) += "el" + +>> "hello".slice(to=-2) += "hell" + +>> "hello".slice(from=2) += "ello" + +``` +## Text.split + +```tomo +Text.split : func(text: Text, delimiter: Text = "" -> [Text]) +``` + +Splits the text into a list of substrings based on exact matches of a delimiter. **Note:** to split based on a set of delimiter characters, use [`split_any()`](#split_any). + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be split. | +delimiter | `Text` | The delimiter used to split the text. If the delimiter is the empty text, the text will be split into individual grapheme clusters. | **Default:** `""` + +**Return:** A list of subtexts resulting from the split. + + +**Example:** +```tomo +>> "one,two,,three".split(",") += ["one", "two", "", "three"] + +>> "abc".split() += ["a", "b", "c"] + +``` +## Text.split_any + +```tomo +Text.split_any : func(text: Text, delimiters: Text = " $\t\r\n" -> [Text]) +``` + +Splits the text into a list of substrings at one or more occurrences of a set of delimiter characters (grapheme clusters). **Note:** to split based on an exact delimiter, use [`split()`](#split). + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be split. | +delimiters | `Text` | A text containing multiple delimiters to be used for splitting the text into chunks. | **Default:** `" $\t\r\n"` + +**Return:** A list of subtexts resulting from the split. + + +**Example:** +```tomo +>> "one, two,,three".split_any(", ") += ["one", "two", "three"] + +``` +## Text.starts_with + +```tomo +Text.starts_with : func(text: Text, prefix: Text -> Bool) +``` + +Checks if the `Text` starts with a literal prefix text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be searched. | +prefix | `Text` | The literal prefix text to check for. | + +**Return:** `yes` if the text has the given prefix, `no` otherwise. + + +**Example:** +```tomo +>> "hello world".starts_with("hello") += yes + +``` +## Text.title + +```tomo +Text.title : func(text: Text, language: Text = "C" -> Text) +``` + +Converts the text to title case (capitalizing the first letter of each word). + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be converted to title case. | +language | `Text` | The ISO 639 language code for which casing rules to use. | **Default:** `"C"` + +**Return:** The text in title case. + + +**Example:** +```tomo +>> "amélie".title() += "Amélie" + +# In Turkish, uppercase "i" is "İ" +>> "i".title(language="tr_TR") += "İ" + +``` +## Text.to + +```tomo +Text.to : func(text: Text, last: Int -> Text) +``` + +Get a slice of the text, ending at the given position. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be sliced. | +last | `Int` | The index of the last grapheme cluster to include (1-indexed). | + +**Return:** The text up to and including the given grapheme cluster. Note: a negative index counts backwards from the end of the text, so `-1` refers to the last cluster, `-2` the second-to-last, etc. Slice ranges will be truncated to the length of the text. + + +**Example:** +```tomo +>> "goodbye".to(3) += "goo" + +>> "goodbye".to(-2) += "goodby" + +``` +## Text.translate + +```tomo +Text.translate : func(translations: {Text=Text} -> Text) +``` + +Takes a table mapping target texts to their replacements and performs all the replacements in the table on the whole text. At each position, the first matching replacement is applied and the matching moves on to *after* the replacement text, so replacement text is not recursively modified. See [`replace()`](#replace) for more information about replacement behavior. + +Argument | Type | Description | Default +---------|------|-------------|--------- +translations | `{Text=Text}` | A table mapping from target text to its replacement. | + +**Return:** The text with all occurrences of the targets replaced with their corresponding replacement text. + + +**Example:** +```tomo +>> "A & an amperand".translate({ +"&" = "&", +"<" = "<", +">" = ">", +'"" = """, +"'" = "'", +} += "A <tag> & an ampersand" + +``` +## Text.trim + +```tomo +Text.trim : func(text: Text, to_trim: Text = " $\t\r\n", left: Bool = yes, right: Bool = yes -> Text) +``` + +Trims the given characters (grapheme clusters) from the left and/or right side of the text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be trimmed. | +to_trim | `Text` | The characters to remove from the left/right of the text. | **Default:** `" $\t\r\n"` +left | `Bool` | Whether or not to trim from the front of the text. | **Default:** `yes` +right | `Bool` | Whether or not to trim from the back of the text. | **Default:** `yes` + +**Return:** The text without the trim characters at either end. + + +**Example:** +```tomo +>> " x y z \n".trim() += "x y z" + +>> "one,".trim(",") += "one" + +>> " xyz ".trim(right=no) += "xyz " + +``` +## Text.upper + +```tomo +Text.upper : func(text: Text, language: Text = "C" -> Text) +``` + +Converts all characters in the text to uppercase. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to be converted to uppercase. | +language | `Text` | The ISO 639 language code for which casing rules to use. | **Default:** `"C"` + +**Return:** The uppercase version of the text. + + +**Example:** +```tomo +>> "amélie".upper() += "AMÉLIE" + +# In Turkish, uppercase "i" is "İ" +>> "i".upper(language="tr_TR") += "İ" + +``` +## Text.utf32_codepoints + +```tomo +Text.utf32_codepoints : func(text: Text -> [Int32]) +``` + +Returns a list of Unicode code points for UTF32 encoding of the text. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text from which to extract Unicode code points. | + +**Return:** A list of 32-bit integer Unicode code points (`[Int32]`). + + +**Example:** +```tomo +>> "Amélie".utf32_codepoints() += [65, 109, 233, 108, 105, 101] + +``` +## Text.width + +```tomo +Text.width : func(text: Text -> Int) +``` + +Returns the display width of the text as seen in a terminal with appropriate font rendering. This is usually the same as the text's `.length`, but there are some characters like emojis that render wider than 1 cell. + +This will not always be exactly accurate when your terminal's font rendering can't handle some unicode displaying correctly. + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text whose length you want. | + +**Return:** An integer representing the display width of the text. + + +**Example:** +```tomo +>> "Amélie".width() += 6 +>> "🤠".width() += 2 + +``` +## Text.without_prefix + +```tomo +Text.without_prefix : func(text: Text, prefix: Text -> Text) +``` + +Returns the text with a given prefix removed (if present). + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to remove the prefix from. | +prefix | `Text` | The prefix to remove. | + +**Return:** A text without the given prefix (if present) or the unmodified text if the prefix is not present. + + +**Example:** +```tomo +>> "foo:baz".without_prefix("foo:") += "baz" +>> "qux".without_prefix("foo:") += "qux" + +``` +## Text.without_suffix + +```tomo +Text.without_suffix : func(text: Text, suffix: Text -> Text) +``` + +Returns the text with a given suffix removed (if present). + +Argument | Type | Description | Default +---------|------|-------------|--------- +text | `Text` | The text to remove the suffix from. | +suffix | `Text` | The suffix to remove. | + +**Return:** A text without the given suffix (if present) or the unmodified text if the suffix is not present. + + +**Example:** +```tomo +>> "baz.foo".without_suffix(".foo") += "baz" +>> "qux".without_suffix(".foo") += "qux" + +``` diff --git a/api/text.yaml b/api/text.yaml new file mode 100644 index 00000000..fbdad3f5 --- /dev/null +++ b/api/text.yaml @@ -0,0 +1,915 @@ +Text.as_c_string: + description: > + Converts a `Text` value to a C-style string. + return: + type: 'CString' + description: > + A C-style string (`CString`) representing the text. + args: + text: + type: 'Text' + description: > + The text to be converted to a C-style string. + example: | + >> "Hello".as_c_string() + = CString("Hello") + +Text.at: + description: > + Get the graphical cluster at a given index. This is similar to `str[i]` with + ASCII text, but has more correct behavior for unicode text. + return: + type: 'Text' + description: > + A `Text` with the single graphical cluster at the given index. Note: negative + indices are counted from the back of the text, so `-1` means the last cluster, + `-2` means the second-to-last, and so on. + args: + text: + type: 'Text' + description: > + The text from which to get a cluster. + index: + type: 'Int' + description: > + The index of the graphical cluster (1-indexed). + example: | + >> "Amélie".at(3) + = "é" + +Text.by_line: + description: > + Returns an iterator function that can be used to iterate over the lines in a + text. + return: + type: 'func(->Text?)' + description: > + An iterator function that returns one line at a time, until it runs out and + returns `none`. **Note:** this function ignores a trailing newline if there is + one. If you don't want this behavior, use `text.by_split($/{1 nl}/)` instead. + args: + text: + type: 'Text' + description: > + The text to be iterated over, line by line. + example: | + text := " + line one + line two + " + for line in text.by_line() + # Prints: "line one" then "line two": + say(line) + +Text.by_split: + description: > + Returns an iterator function that can be used to iterate over text separated by + a delimiter. + **Note:** to split based on a set of delimiters, use [`by_split_any()`](#by_split_any). + return: + type: 'func(->Text?)' + description: > + An iterator function that returns one chunk of text at a time, separated by the + given delimiter, until it runs out and returns `none`. **Note:** using an empty + delimiter (the default) will iterate over single grapheme clusters in the text. + args: + text: + type: 'Text' + description: > + The text to be iterated over in delimited chunks. + delimiter: + type: 'Text' + default: '""' + description: > + An exact delimiter to use for splitting the text. + note: > + If an empty text is given as the delimiter, then each split will be the + graphical clusters of the text. + example: | + text := "one,two,three" + for chunk in text.by_split(",") + # Prints: "one" then "two" then "three": + say(chunk) + +Text.by_split_any: + description: > + Returns an iterator function that can be used to iterate over text separated by + one or more characters (grapheme clusters) from a given text of delimiters. + **Note:** to split based on an exact delimiter, use [`by_split()`](#by_split). + return: + type: 'func(->Text?)' + description: > + An iterator function that returns one chunk of text at a time, separated by the + given delimiter characters, until it runs out and returns `none`. + args: + text: + type: 'Text' + description: > + The text to be iterated over in delimited chunks. + delimiters: + type: 'Text' + default: '" $\t\r\n"' + description: > + Grapheme clusters to use for splitting the text. + note: > + Splitting will occur on every place where one or more of the grapheme + clusters in `delimiters` occurs. + example: | + text := "one,two,;,three" + for chunk in text.by_split_any(",;") + # Prints: "one" then "two" then "three": + say(chunk) + +Text.bytes: + description: > + Converts a `Text` value to a list of bytes representing a UTF8 encoding of + the text. + return: + type: '[Byte]' + description: > + A list of bytes (`[Byte]`) representing the text in UTF8 encoding. + args: + text: + type: 'Text' + description: > + The text to be converted to UTF8 bytes. + example: | + >> "Amélie".bytes() + = [65, 109, 195, 169, 108, 105, 101] + +Text.caseless_equals: + description: > + Checks whether two texts are equal, ignoring the casing of the letters (i.e. + case-insensitive comparison). + return: + type: 'Bool' + description: > + `yes` if `a` and `b` are equal to each other, ignoring casing, otherwise `no`. + args: + a: + type: 'Text' + description: > + The first text to compare case-insensitively. + b: + type: 'Text' + description: > + The second text to compare case-insensitively. + language: + type: 'Text' + default: '"C"' + description: > + The ISO 639 language code for which casing rules to use. + example: | + >> "A".caseless_equals("a") + = yes + + # Turkish lowercase "I" is "ı" (dotless I), not "i" + >> "I".caseless_equals("i", language="tr_TR") + = no + +Text.codepoint_names: + description: > + Returns a list of the names of each codepoint in the text. + return: + type: '[Text]' + description: > + A list of codepoint names (`[Text]`). + args: + text: + type: 'Text' + description: > + The text from which to extract codepoint names. + example: | + >> "Amélie".codepoint_names() + = ["LATIN CAPITAL LETTER A", "LATIN SMALL LETTER M", "LATIN SMALL LETTER E WITH ACUTE", "LATIN SMALL LETTER L", "LATIN SMALL LETTER I", "LATIN SMALL LETTER E"] + +Text.ends_with: + description: > + Checks if the `Text` ends with a literal suffix text. + return: + type: 'Bool' + description: > + `yes` if the text has the target, `no` otherwise. + args: + text: + type: 'Text' + description: > + The text to be searched. + suffix: + type: 'Text' + description: > + The literal suffix text to check for. + example: | + >> "hello world".ends_with("world") + = yes + +Text.from: + description: > + Get a slice of the text, starting at the given position. + return: + type: 'Text' + description: > + The text from the given grapheme cluster to the end of the text. Note: a + negative index counts backwards from the end of the text, so `-1` refers to the + last cluster, `-2` the second-to-last, etc. Slice ranges will be truncated to + the length of the text. + args: + text: + type: 'Text' + description: > + The text to be sliced. + first: + type: 'Int' + description: > + The index to begin the slice. + example: | + >> "hello".from(2) + = "ello" + + >> "hello".from(-2) + = "lo" + +Text.from_bytes: + description: > + Returns text that has been constructed from the given UTF8 bytes. Note: the + text will be normalized, so the resulting text's UTF8 bytes may not exactly + match the input. + return: + type: '[Text]' + description: > + A new text based on the input UTF8 bytes after normalization has been applied. + args: + bytes: + type: '[Byte]' + description: > + The UTF-8 bytes of the desired text. + example: | + >> Text.from_bytes([195, 133, 107, 101]) + = "Åke" + +Text.from_c_string: + description: > + Converts a C-style string to a `Text` value. + return: + type: 'Text' + description: > + A `Text` value representing the C-style string. + args: + str: + type: 'CString' + description: > + The C-style string to be converted. + example: | + >> Text.from_c_string(CString("Hello")) + = "Hello" + +Text.from_codepoint_names: + description: > + Returns text that has the given codepoint names (according to the Unicode + specification) as its codepoints. Note: the text will be normalized, so the + resulting text's codepoints may not exactly match the input codepoints. + return: + type: '[Text]' + description: > + A new text with the specified codepoints after normalization has been applied. + Any invalid names are ignored. + args: + codepoint_names: + type: '[Text]' + description: > + The names of each codepoint in the desired text (case-insentive). + example: | + >> Text.from_codepoint_names([ + "LATIN CAPITAL LETTER A WITH RING ABOVE", + "LATIN SMALL LETTER K", + "LATIN SMALL LETTER E", + ] + = "Åke" + +Text.from_codepoints: + description: > + Returns text that has been constructed from the given UTF32 codepoints. Note: + the text will be normalized, so the resulting text's codepoints may not exactly + match the input codepoints. + return: + type: '[Text]' + description: > + A new text with the specified codepoints after normalization has been applied. + args: + codepoints: + type: '[Int32]' + description: > + The UTF32 codepoints in the desired text. + example: | + >> Text.from_codepoints([197, 107, 101]) + = "Åke" + +Text.has: + description: > + Checks if the `Text` contains some target text. + return: + type: 'Bool' + description: > + `yes` if the target text is found, `no` otherwise. + args: + text: + type: 'Text' + description: > + The text to be searched. + target: + type: 'Text' + description: > + The text to search for. + example: | + >> "hello world".has("wo") + = yes + >> "hello world".has("xxx") + = no + +Text.join: + description: > + Joins a list of text pieces with a specified glue. + return: + type: 'Text' + description: > + A single `Text` value with the pieces joined by the glue. + args: + glue: + type: 'Text' + description: > + The text used to join the pieces. + pieces: + type: '[Text]' + description: > + The list of text pieces to be joined. + example: | + >> ", ".join(["one", "two", "three"]) + = "one, two, three" + +Text.middle_pad: + description: > + Pad some text on the left and right side so it reaches a target width. + return: + type: 'Text' + description: > + Text with length at least `width`, with extra padding on the left and right as + needed. If `pad` has length greater than 1, it may be partially repeated to + reach the exact desired length. + args: + text: + type: 'Text' + description: > + The text to pad. + width: + type: 'Int' + description: > + The target width. + pad: + type: 'Text' + default: '" "' + description: > + The padding text. + language: + type: 'Text' + default: '"C"' + description: > + The ISO 639 language code for which character width to use. + example: | + >> "x".middle_pad(6) + = " x " + >> "x".middle_pad(10, "ABC") + = "ABCAxABCAB" + +Text.left_pad: + description: > + Pad some text on the left side so it reaches a target width. + return: + type: 'Text' + description: > + Text with length at least `width`, with extra padding on the left as needed. If + `pad` has length greater than 1, it may be partially repeated to reach the + exact desired length. + args: + text: + type: 'Text' + description: > + The text to pad. + width: + type: 'Int' + description: > + The target width. + pad: + type: 'Text' + default: '" "' + description: > + The padding text. + language: + type: 'Text' + default: '"C"' + description: > + The ISO 639 language code for which character width to use. + example: | + >> "x".left_pad(5) + = " x" + >> "x".left_pad(5, "ABC") + = "ABCAx" + +Text.lines: + description: > + Splits the text into a list of lines of text, preserving blank lines, + ignoring trailing newlines, and handling `\r\n` the same as `\n`. + return: + type: '[Text]' + description: > + A list of substrings resulting from the split. + args: + text: + type: 'Text' + description: > + The text to be split into lines. + example: | + >> "one\ntwo\nthree".lines() + = ["one", "two", "three"] + >> "one\ntwo\nthree\n".lines() + = ["one", "two", "three"] + >> "one\ntwo\nthree\n\n".lines() + = ["one", "two", "three", ""] + >> "one\r\ntwo\r\nthree\r\n".lines() + = ["one", "two", "three"] + >> "".lines() + = [] + +Text.lower: + description: > + Converts all characters in the text to lowercase. + return: + type: 'Text' + description: > + The lowercase version of the text. + args: + text: + type: 'Text' + description: > + The text to be converted to lowercase. + language: + type: 'Text' + default: '"C"' + description: > + The ISO 639 language code for which casing rules to use. + example: | + >> "AMÉLIE".lower() + = "amélie" + + >> "I".lower(language="tr_TR") + >> "ı" + +Text.quoted: + description: > + Formats the text with quotation marks and escapes. + return: + type: 'Text' + description: > + The text formatted as a quoted text. + args: + text: + type: 'Text' + description: > + The text to be quoted. + color: + type: 'Bool' + default: 'no' + description: > + Whether to add color formatting. + quotation_mark: + type: 'Text' + default: '`"`' + description: > + The quotation mark to use. + example: | + >> "one\ntwo".quoted() + = "\"one\\ntwo\"" + +Text.repeat: + description: > + Repeat some text multiple times. + return: + type: 'Text' + description: > + The text repeated the given number of times. + args: + text: + type: 'Text' + description: > + The text to repeat. + count: + type: 'Int' + description: > + The number of times to repeat it. (Negative numbers are equivalent to zero). + example: | + >> "Abc".repeat(3) + = "AbcAbcAbc" + +Text.replace: + description: > + Replaces occurrences of a target text with a replacement text. + return: + type: 'Text' + description: > + The text with occurrences of the target replaced. + args: + text: + type: 'Text' + description: > + The text in which to perform replacements. + target: + type: 'Text' + description: > + The target text to be replaced. + replacement: + type: 'Text' + description: > + The text to replace the target with. + example: | + >> "Hello world".replace("world", "there") + = "Hello there" + +Text.reversed: + description: > + Return a text that has the grapheme clusters in reverse order. + return: + type: 'Text' + description: > + A reversed version of the text. + args: + text: + type: 'Text' + description: > + The text to reverse. + example: | + >> "Abc".reversed() + = "cbA" + +Text.right_pad: + description: > + Pad some text on the right side so it reaches a target width. + return: + type: 'Text' + description: > + Text with length at least `width`, with extra padding on the right as needed. If + `pad` has length greater than 1, it may be partially repeated to reach the + exact desired length. + args: + text: + type: 'Text' + description: > + The text to pad. + width: + type: 'Int' + description: > + The target width. + pad: + type: 'Text' + default: '" "' + description: > + The padding text. + language: + type: 'Text' + default: '"C"' + description: > + The ISO 639 language code for which character width to use. + example: | + >> "x".right_pad(5) + = "x " + >> "x".right_pad(5, "ABC") + = "xABCA" + +Text.slice: + description: > + Get a slice of the text. + return: + type: 'Text' + description: > + The text that spans the given grapheme cluster indices. Note: a negative index + counts backwards from the end of the text, so `-1` refers to the last cluster, + `-2` the second-to-last, etc. Slice ranges will be truncated to the length of + the text. + args: + text: + type: 'Text' + description: > + The text to be sliced. + from: + type: 'Int' + default: '1' + description: > + The index of the first grapheme cluster to include (1-indexed). + to: + type: 'Int' + default: '-1' + description: > + The index of the last grapheme cluster to include (1-indexed). + example: | + >> "hello".slice(2, 3) + = "el" + + >> "hello".slice(to=-2) + = "hell" + + >> "hello".slice(from=2) + = "ello" + +Text.split: + description: > + Splits the text into a list of substrings based on exact matches of a delimiter. + **Note:** to split based on a set of delimiter characters, use [`split_any()`](#split_any). + return: + type: '[Text]' + description: > + A list of subtexts resulting from the split. + args: + text: + type: 'Text' + description: > + The text to be split. + delimiter: + type: 'Text' + default: '""' + description: > + The delimiter used to split the text. If the delimiter is the + empty text, the text will be split into individual grapheme clusters. + example: | + >> "one,two,,three".split(",") + = ["one", "two", "", "three"] + + >> "abc".split() + = ["a", "b", "c"] + +Text.split_any: + description: > + Splits the text into a list of substrings at one or more occurrences of a set + of delimiter characters (grapheme clusters). + **Note:** to split based on an exact delimiter, use [`split()`](#split). + return: + type: '[Text]' + description: > + A list of subtexts resulting from the split. + args: + text: + type: 'Text' + description: > + The text to be split. + delimiters: + type: 'Text' + default: '" $\t\r\n"' + description: > + A text containing multiple delimiters to be used for + splitting the text into chunks. + example: | + >> "one, two,,three".split_any(", ") + = ["one", "two", "three"] + +Text.starts_with: + description: > + Checks if the `Text` starts with a literal prefix text. + return: + type: 'Bool' + description: > + `yes` if the text has the given prefix, `no` otherwise. + args: + text: + type: 'Text' + description: > + The text to be searched. + prefix: + type: 'Text' + description: > + The literal prefix text to check for. + example: | + >> "hello world".starts_with("hello") + = yes + +Text.title: + description: > + Converts the text to title case (capitalizing the first letter of each word). + return: + type: 'Text' + description: > + The text in title case. + args: + text: + type: 'Text' + description: > + The text to be converted to title case. + language: + type: 'Text' + default: '"C"' + description: > + The ISO 639 language code for which casing rules to use. + example: | + >> "amélie".title() + = "Amélie" + + # In Turkish, uppercase "i" is "İ" + >> "i".title(language="tr_TR") + = "İ" + +Text.to: + description: > + Get a slice of the text, ending at the given position. + return: + type: 'Text' + description: > + The text up to and including the given grapheme cluster. Note: a negative index + counts backwards from the end of the text, so `-1` refers to the last cluster, + `-2` the second-to-last, etc. Slice ranges will be truncated to the length of + the text. + args: + text: + type: 'Text' + description: > + The text to be sliced. + last: + type: 'Int' + description: > + The index of the last grapheme cluster to include (1-indexed). + example: | + >> "goodbye".to(3) + = "goo" + + >> "goodbye".to(-2) + = "goodby" + +Text.translate: + description: > + Takes a table mapping target texts to their replacements and performs all the + replacements in the table on the whole text. At each position, the first + matching replacement is applied and the matching moves on to *after* the + replacement text, so replacement text is not recursively modified. See + [`replace()`](#replace) for more information about replacement behavior. + return: + type: 'Text' + description: > + The text with all occurrences of the targets replaced with their corresponding + replacement text. + args: + translations: + type: '{Text=Text}' + description: > + A table mapping from target text to its replacement. + example: | + >> "A & an amperand".translate({ + "&" = "&", + "<" = "<", + ">" = ">", + '"" = """, + "'" = "'", + } + = "A <tag> & an ampersand" + +Text.trim: + description: > + Trims the given characters (grapheme clusters) from the left and/or right side of the text. + return: + type: 'Text' + description: > + The text without the trim characters at either end. + args: + text: + type: 'Text' + description: > + The text to be trimmed. + to_trim: + type: 'Text' + default: '" $\t\r\n"' + description: > + The characters to remove from the left/right of the text. + left: + type: 'Bool' + default: 'yes' + description: > + Whether or not to trim from the front of the text. + right: + type: 'Bool' + default: 'yes' + description: > + Whether or not to trim from the back of the text. + example: | + >> " x y z \n".trim() + = "x y z" + + >> "one,".trim(",") + = "one" + + >> " xyz ".trim(right=no) + = "xyz " + +Text.upper: + description: > + Converts all characters in the text to uppercase. + return: + type: 'Text' + description: > + The uppercase version of the text. + args: + text: + type: 'Text' + description: > + The text to be converted to uppercase. + language: + type: 'Text' + default: '"C"' + description: > + The ISO 639 language code for which casing rules to use. + example: | + >> "amélie".upper() + = "AMÉLIE" + + # In Turkish, uppercase "i" is "İ" + >> "i".upper(language="tr_TR") + = "İ" + +Text.utf32_codepoints: + description: > + Returns a list of Unicode code points for UTF32 encoding of the text. + return: + type: '[Int32]' + description: > + A list of 32-bit integer Unicode code points (`[Int32]`). + args: + text: + type: 'Text' + description: > + The text from which to extract Unicode code points. + example: | + >> "Amélie".utf32_codepoints() + = [65, 109, 233, 108, 105, 101] + +Text.width: + description: > + Returns the display width of the text as seen in a terminal with appropriate + font rendering. This is usually the same as the text's `.length`, but there are + some characters like emojis that render wider than 1 cell. + note: > + This will not always be exactly accurate when your terminal's font + rendering can't handle some unicode displaying correctly. + return: + type: 'Int' + description: > + An integer representing the display width of the text. + args: + text: + type: 'Text' + description: > + The text whose length you want. + example: | + >> "Amélie".width() + = 6 + >> "🤠".width() + = 2 + +Text.without_prefix: + description: > + Returns the text with a given prefix removed (if present). + return: + type: 'Text' + description: > + A text without the given prefix (if present) or the unmodified text if the + prefix is not present. + args: + text: + type: 'Text' + description: > + The text to remove the prefix from. + prefix: + type: 'Text' + description: > + The prefix to remove. + example: | + >> "foo:baz".without_prefix("foo:") + = "baz" + >> "qux".without_prefix("foo:") + = "qux" + +Text.without_suffix: + description: > + Returns the text with a given suffix removed (if present). + return: + type: 'Text' + description: > + A text without the given suffix (if present) or the unmodified text if the + suffix is not present. + args: + text: + type: 'Text' + description: > + The text to remove the suffix from. + suffix: + type: 'Text' + description: > + The suffix to remove. + example: | + >> "baz.foo".without_suffix(".foo") + = "baz" + >> "qux".without_suffix(".foo") + = "qux" + diff --git a/docs/booleans.md b/docs/booleans.md index 8961091a..a3ad22d0 100644 --- a/docs/booleans.md +++ b/docs/booleans.md @@ -3,32 +3,6 @@ Boolean values have the type `Bool` and can be either `yes` ("true") or `no` ("false"). -## Boolean Functions +# API -This documentation provides details on boolean functions available in the API. - -- [`func parse(text: Text -> Bool?)`](#parse) - -### `parse` -Converts a string representation of a boolean value into a boolean. Acceptable -boolean values are case-insensitive variations of `yes`/`no`, `y`/`n`, -`true`/`false`, `on`/`off`. - -```tomo -func parse(text: Text -> Bool?) -``` - -- `text`: The string containing the boolean value. - -**Returns:** -`yes` if the string matches a recognized truthy boolean value; otherwise return `no`. - -**Example:** -```tomo ->> Bool.parse("yes") -= yes : Bool? ->> Bool.parse("no") -= no : Bool? ->> Bool.parse("???") -= none : Bool? -``` +[API documentation](../api/booleans.md) diff --git a/docs/builtins.md b/docs/builtins.md deleted file mode 100644 index f1d8069f..00000000 --- a/docs/builtins.md +++ /dev/null @@ -1,184 +0,0 @@ -# Built-in Functions - -These are the top-level functions built into Tomo. - -- [`func ask(prompt:Text, bold:Bool = yes, force_tty:Bool = yes -> Text?)`](#ask) -- [`func ask(message:Text? = !Text, status:Int32 = 1[32] -> Void)`](#exit) -- [`func getenv(name:Text -> Text?)`](#getenv) -- [`func print(text:Text, newline:Bool = yes -> Void)`](#print) -- [`func say(text:Text, newline:Bool = yes -> Void)`](#say) -- [`func setenv(name:Text, value:Text)`](#setenv) -- [`func sleep(seconds: Num -> Void)`](#sleep) -- [`func fail(message:Text -> Abort)`](#fail) - ---- - -### `ask` -Gets a line of user input text with a prompt. - -```tomo -func ask(prompt:Text, bold:Bool = yes, force_tty:Bool = yes -> Text?) -``` - -- `prompt`: The text to print as a prompt before getting the input. -- `bold`: Whether or not to print make the prompt appear bold on a console - using the ANSI escape sequence `\x1b[1m`. -- `force_tty`: When a program is receiving input from a pipe or writing its - output to a pipe, this flag (which is enabled by default) forces the program - to write the prompt to `/dev/tty` and read the input from `/dev/tty`, which - circumvents the pipe. This means that `foo | ./tomo your-program | baz` will - still show a visible prompt and read user input, despite the pipes. Setting - this flag to `no` will mean that the prompt is written to `stdout` and input - is read from `stdin`, even if those are pipes. - -**Returns:** -A line of user input text without a trailing newline, or empty text if -something went wrong (e.g. the user hit `Ctrl-D`). - -**Example:** -```tomo ->> ask("What's your name? ") -= "Arthur Dent" -``` - ---- - -### `exit` -Exits the program with a given status and optionally prints a message. - -```tomo -func exit(message:Text? = !Text, status:Int32 = 1[32] -> Void) -``` - -- `message`: If nonempty, this message will be printed (with a newline) before - exiting. -- `status`: The status code that the program with exit with (default: 1, which - is a failure status). - -**Returns:** -This function never returns. - -**Example:** -```tomo -exit(status=1, "Goodbye forever!") -``` - ---- - -### `getenv` -Gets an environment variable. - -```tomo -func getenv(name:Text -> Text?) -``` - -- `name`: The name of the environment variable to get. - -**Returns:** -If set, the environment variable's value, otherwise, `none`. - -**Example:** -```tomo ->> getenv("TERM") -= "xterm-256color"? -``` - ---- - -### `print` -Prints a message to the console (alias for [`say`](#say)). - -```tomo -func print(text:Text, newline:Bool = yes -> Void) -``` - -- `text`: The text to print. -- `newline`: Whether or not to print a newline after the text. - -**Returns:** -Nothing. - -**Example:** -```tomo -print("Hello ", newline=no) -print("world!") -``` - ---- - -### `say` -Prints a message to the console. - -```tomo -func say(text:Text, newline:Bool = yes -> Void) -``` - -- `text`: The text to print. -- `newline`: Whether or not to print a newline after the text. - -**Returns:** -Nothing. - -**Example:** -```tomo -say("Hello ", newline=no) -say("world!") -``` - ---- - -### `setenv` -Sets an environment variable. - -```tomo -func getenv(name:Text, value:Text -> Void) -``` - -- `name`: The name of the environment variable to set. -- `value`: The new value of the environment variable. - -**Returns:** -Nothing. - -**Example:** -```tomo -setenv("FOOBAR", "xyz") -``` - ---- - -### `sleep` -Pause execution for a given number of seconds. - -```tomo -func sleep(seconds: Num -> Void) -``` - -- `seconds`: How many seconds to sleep for. - -**Returns:** -Nothing. - -**Example:** -```tomo -sleep(1.5) -``` - ---- - -### `fail` -Prints a message to the console, aborts the program, and prints a stack trace. - -```tomo -func fail(message:Text -> Abort) -``` - -- `message`: The error message to print. - -**Returns:** -Nothing, aborts the program. - -**Example:** -```tomo -fail("Oh no!") -``` diff --git a/docs/bytes.md b/docs/bytes.md index 2e139622..196d5762 100644 --- a/docs/bytes.md +++ b/docs/bytes.md @@ -7,53 +7,6 @@ API methods for `Text` and `Path` that deal with raw binary data, such as `Path.read_bytes()` and `Text.bytes()`. Byte literals can be written using the `Byte()` constructor: `Byte(5)`. -# Byte Methods +# API -- [`func hex(byte: Byte, uppercase=no, prefix=yes -> Text)`](#hex) -- [`func is_between(x: Byte, low: Byte, high: Byte -> Bool)`](#is_between) -- [`func parse(text: Text -> Byte?)`](#parse) -- [`func to(first: Byte, last: Byte, step: Int8? = none -> Text)`](#to) - ---------- - -## `hex` - -TODO: write docs - ---------- - -### `is_between` -Determines if an integer is between two numbers (inclusive). - -```tomo -func is_between(x: Byte, low: Byte, high: Byte -> Bool) -``` - -- `x`: The integer to be checked. -- `low`: The lower bound to check (inclusive). -- `high`: The upper bound to check (inclusive). - -**Returns:** -`yes` if `low <= x and x <= high`, otherwise `no` - -**Example:** -```tomo ->> Byte(7).is_between(1, 10) -= yes ->> Byte(7).is_between(100, 200) -= no ->> Byte(7).is_between(1, 7) -= yes -``` - ---- - -## `parse` - -TODO: write docs - ---------- - -## `to` - -TODO: write docs +[API documentation](../api/bytes.md) diff --git a/docs/integers.md b/docs/integers.md index b37f93ab..6be96880 100644 --- a/docs/integers.md +++ b/docs/integers.md @@ -116,394 +116,6 @@ rounding _towards zero_, and modulus never gives negative results: = yes ``` -## Integer Functions +# API -Each integer type has its own version of the following functions. Functions -can be called either on the type itself: `Int.sqrt(x)` or as a method call: -`x.sqrt()`. Method call syntax is preferred. - -- [`func abs(x: Int -> Int)`](#abs) -- [`func choose(n: Int, k: Int -> Int)`](#choose) -- [`func clamped(x, low, high: Int -> Int)`](#clamped) -- [`func factorial(n: Int -> Text)`](#factorial) -- [`func format(i: Int, digits: Int = 0 -> Text)`](#format) -- [`func hex(i: Int, digits: Int = 0, uppercase: Bool = yes, prefix: Bool = yes -> Text)`](#hex) -- [`func is_between(x: Int, low: Int, high: Int -> Bool)`](#is_between) -- [`func is_prime(x: Int, reps: Int = 50 -> Bool)`](#is_prime) -- [`func next_prime(x: Int -> Int)`](#next_prime) -- [`func octal(i: Int, digits: Int = 0, prefix: Bool = yes -> Text)`](#octal) -- [`func onward(first: Int, step: Int = 1 -> Text)`](#onward) -- [`func parse(text: Text -> Int?)`](#parse) -- [`func prev_prime(x: Int -> Int?)`](#prev_prime) -- [`func sqrt(x: Int -> Int)`](#sqrt) -- [`func to(first: Int, last: Int, step : Int? = none -> func(->Int?))`](#to) - -### `abs` -Calculates the absolute value of an integer. - -```tomo -func abs(x: Int -> Int) -``` - -- `x`: The integer whose absolute value is to be calculated. - -**Returns:** -The absolute value of `x`. - -**Example:** -```tomo ->> (-10).abs() -= 10 -``` - ---- - -### `choose` -Computes the binomial coefficient of the given numbers (the equivalent of `n` -choose `k` in combinatorics). This is equal to `n.factorial()/(k.factorial() * -(n-k).factorial())`. - -```tomo -func choose(n: Int, k: Int -> Int) -``` - -- `n`: The number of things to choose from. -- `k`: The number of things to be chosen. - -**Returns:** -The binomial coefficient, equivalent to the number of ways to uniquely choose -`k` objects from among `n` objects, ignoring order. - -**Example:** -```tomo ->> (4).choose(2) -= 6 -``` - ---- - -### `clamped` -Returns the given number clamped between two values so that it is within -that range. - -```tomo -func clamped(x, low, high: Int -> Int) -``` - -- `x`: The integer to clamp. -- `low`: The lowest value the result can take. -- `high`: The highest value the result can take. - -**Returns:** -The first argument clamped between the other two arguments. - -**Example:** -```tomo ->> (2).clamped(5, 10) -= 5 -``` - ---- - -### `factorial` -Computes the factorial of an integer. - -```tomo -func factorial(n: Int -> Text) -``` - -- `n`: The integer to compute the factorial of. - -**Returns:** -The factorial of the given integer. - -**Example:** -```tomo ->> (10).factorial() -= 3628800 -``` - ---- - -### `format` -Formats an integer as a string with a specified number of digits. - -```tomo -func format(i: Int, digits: Int = 0 -> Text) -``` - -- `i`: The integer to be formatted. -- `digits`: The minimum number of digits to which the integer should be padded. Default is `0`. - -**Returns:** -A string representation of the integer, padded to the specified number of digits. - -**Example:** -```tomo ->> (42).format(digits=5) -= "00042" -``` - ---- - -### `hex` -Converts an integer to its hexadecimal representation. - -```tomo -func hex(i: Int, digits: Int = 0, uppercase: Bool = yes, prefix: Bool = yes -> Text) -``` - -- `i`: The integer to be converted. -- `digits`: The minimum number of digits in the output string. Default is `0`. -- `uppercase`: Whether to use uppercase letters for hexadecimal digits. Default is `yes`. -- `prefix`: Whether to include a "0x" prefix. Default is `yes`. - -**Returns:** -The hexadecimal string representation of the integer. - -**Example:** -```tomo ->> (255).hex(digits=4, uppercase=yes, prefix=yes) -= "0x00FF" -``` - ---- - -### `is_between` -Determines if an integer is between two numbers (inclusive). - -```tomo -func is_between(x: Int, low: Int, high: Int -> Bool) -``` - -- `x`: The integer to be checked. -- `low`: The lower bound to check (inclusive). -- `high`: The upper bound to check (inclusive). - -**Returns:** -`yes` if `low <= x and x <= high`, otherwise `no` - -**Example:** -```tomo ->> (7).is_between(1, 10) -= yes ->> (7).is_between(100, 200) -= no ->> (7).is_between(1, 7) -= yes -``` - ---- - -### `is_prime` -Determines if an integer is a prime number. - -**Note:** -This function is _probabilistic_. With the default arguments, the chances of -getting an incorrect answer are astronomically small (on the order of 10^(-30)). -See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp) -for more details. - -```tomo -func is_prime(x: Int, reps: Int = 50 -> Bool) -``` - -- `x`: The integer to be checked. -- `reps`: The number of repetitions for primality tests. Default is `50`. - -**Returns:** -`yes` if `x` is a prime number, `no` otherwise. - -**Example:** -```tomo ->> (7).is_prime() -= yes ->> (6).is_prime() -= no -``` - ---- - -### `next_prime` -Finds the next prime number greater than the given integer. - -**Note:** -This function is _probabilistic_, but the chances of getting an incorrect -answer are astronomically small (on the order of 10^(-30)). -See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp) -for more details. - -```tomo -func next_prime(x: Int -> Int) -``` - -- `x`: The integer after which to find the next prime. - -**Returns:** -The next prime number greater than `x`. - -**Example:** -```tomo ->> (11).next_prime() -= 13 -``` - ---- - -### `octal` -Converts an integer to its octal representation. - -```tomo -func octal(i: Int, digits: Int = 0, prefix: Bool = yes -> Text) -``` - -- `i`: The integer to be converted. -- `digits`: The minimum number of digits in the output string. Default is `0`. -- `prefix`: Whether to include a "0o" prefix. Default is `yes`. - -**Returns:** -The octal string representation of the integer. - -**Example:** -```tomo ->> (64).octal(digits=4, prefix=yes) -= "0o0100" -``` - ---- - -### `onward` -Return an iterator that counts infinitely from the starting integer (with an -optional step size). - -```tomo -func onward(first: Int, step: Int = 1 -> Text) -``` - -- `first`: The starting integer. -- `step`: The increment step size (default: 1). - -**Returns:** -An iterator function that counts onward from the starting integer. - -**Example:** -```tomo -nums : &[Int] = &[] -for i in (5).onward() - nums.insert(i) - stop if i == 10 ->> nums[] -= [5, 6, 7, 8, 9, 10] -``` - ---- - -### `parse` -Converts a text representation of an integer into an integer. - -```tomo -func parse(text: Text -> Int?) -``` - -- `text`: The text containing the integer. - -**Returns:** -The integer represented by the text. If the given text contains a value outside -of the representable range or if the entire text can't be parsed as an integer, -`none` will be returned. - -**Example:** -```tomo ->> Int.parse("123") -= 123 : Int? ->> Int.parse("0xFF") -= 255 : Int? - -# Can't parse: ->> Int.parse("asdf") -= none : Int? - -# Outside valid range: ->> Int8.parse("9999999") -= none : Int8? -``` - ---- - -### `prev_prime` -Finds the previous prime number less than the given integer. -If there is no previous prime number (i.e. if a number less than `2` is -provided), then the function will create a runtime error. - -**Note:** -This function is _probabilistic_, but the chances of getting an incorrect -answer are astronomically small (on the order of 10^(-30)). -See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp) -for more details. - -```tomo -func prev_prime(x: Int -> Int?) -``` - -- `x`: The integer before which to find the previous prime. - -**Returns:** -The previous prime number less than `x`, or `none` if `x` is less than 2. - -**Example:** -```tomo ->> (11).prev_prime() -= 7 -``` - ---- - -### `sqrt` -Calculates the square root of an integer. - -```tomo -func sqrt(x: Int -> Int) -``` - -- `x`: The integer whose square root is to be calculated. - -**Returns:** -The integer part of the square root of `x`. - -**Example:** -```tomo ->> (16).sqrt() -= 4 ->> (17).sqrt() -= 4 -``` - ---- - -### `to` -Returns an iterator function that iterates over the range of numbers specified. -Iteration is assumed to be nonempty and - -```tomo -func to(first: Int, last: Int, step : Int? = none -> func(->Int?)) -``` - -- `first`: The starting value of the range. -- `last`: The ending value of the range. -- `step`: An optional step size to use. If unspecified or `none`, the step will be inferred to be `+1` if `last >= first`, otherwise `-1`. - -**Returns:** -An iterator function that returns each integer in the given range (inclusive). - -**Example:** -```tomo ->> (2).to(5) -= func(->Int?) ->> [x for x in (2).to(5)] -= [2, 3, 4, 5] ->> [x for x in (5).to(2)] -= [5, 4, 3, 2] - ->> [x for x in (2).to(5, step=2)] -= [2, 4] -``` +[API documentation](../api/integers.md) diff --git a/docs/lists.md b/docs/lists.md index 141f6abd..dfb64aad 100644 --- a/docs/lists.md +++ b/docs/lists.md @@ -231,680 +231,6 @@ The TL;DR is: you can cheaply modify local variables that aren't aliased or `@`-allocated lists, but if you assign a local variable list to another variable or dereference a heap pointer, it may trigger copy-on-write behavior. -## List Methods - -- [`func binary_search(list: [T], by: func(x,y:&T->Int32) = T.compare -> Int)`](#binary_search) -- [`func by(list: [T], step: Int -> [T])`](#by) -- [`func clear(list: @[T] -> Void)`](#clear) -- [`func counts(list: [T] -> {T=Int})`](#counts) -- [`func find(list: [T], target: T -> Int?)`](#find) -- [`func first(list: [T], predicate: func(item:&T -> Bool) -> Int)`](#first) -- [`func from(list: [T], first: Int -> [T])`](#from) -- [`func has(list: [T], element: T -> Bool)`](#has) -- [`func heap_pop(list: @[T], by: func(x,y:&T->Int32) = T.compare -> T?)`](#heap_pop) -- [`func heap_push(list: @[T], item: T, by=T.compare -> Void)`](#heap_push) -- [`func heapify(list: @[T], by: func(x,y:&T->Int32) = T.compare -> Void)`](#heapify) -- [`func insert(list: @[T], item: T, at: Int = 0 -> Void)`](#insert) -- [`func insert_all(list: @[T], items: [T], at: Int = 0 -> Void)`](#insert_all) -- [`func pop(list: &[T], index: Int = -1 -> T?)`](#pop) -- [`func random(list: [T], random: func(min,max:Int64->Int64)? = none -> T)`](#random) -- [`func remove_at(list: @[T], at: Int = -1, count: Int = 1 -> Void)`](#remove_at) -- [`func remove_item(list: @[T], item: T, max_count: Int = -1 -> Void)`](#remove_item) -- [`func reversed(list: [T] -> [T])`](#reversed) -- [`func sample(list: [T], count: Int, weights: [Num]? = ![Num], random: func(->Num)? = none -> [T])`](#sample) -- [`func shuffle(list: @[T], random: func(min,max:Int64->Int64)? = none -> Void)`](#shuffle) -- [`func shuffled(list: [T], random: func(min,max:Int64->Int64)? = none -> [T])`](#shuffled) -- [`func slice(list: [T], from: Int, to: Int -> [T])`](#slice) -- [`func sort(list: @[T], by=T.compare -> Void)`](#sort) -- [`sorted(list: [T], by=T.compare -> [T])`](#sorted) -- [`to(list: [T], last: Int -> [T])`](#to) -- [`unique(list: [T] -> {T})`](#unique) - -### `binary_search` -Performs a binary search on a sorted list. +# API -```tomo -func binary_search(list: [T], by: func(x,y:&T->Int32) = T.compare -> Int) -``` - -- `list`: The sorted list to search. -- `by`: The comparison function used to determine order. If not specified, the - default comparison function for the item type will be used. - -**Returns:** -Assuming the input list is sorted according to the given comparison function, -return the index where the given item would be inserted to maintain the sorted -order. That is, if the item is found, return its index, otherwise return the -place where it would be found if it were inserted and the list were sorted. - -**Example:** -```tomo ->> [1, 3, 5, 7, 9].binary_search(5) -= 3 - ->> [1, 3, 5, 7, 9].binary_search(-999) -= 1 - ->> [1, 3, 5, 7, 9].binary_search(999) -= 6 -``` - ---- - -### `by` -Creates a new list with elements spaced by the specified step value. - -```tomo -func by(list: [T], step: Int -> [T]) -``` - -- `list`: The original list. -- `step`: The step value for selecting elements. - -**Returns:** -A new list with every `step`-th element from the original list. - -**Example:** -```tomo ->> [1, 2, 3, 4, 5, 6].by(2) -= [1, 3, 5] -``` - ---- - -### `clear` -Clears all elements from the list. - -```tomo -func clear(list: @[T] -> Void) -``` - -- `list`: The mutable reference to the list to be cleared. - -**Returns:** -Nothing. - -**Example:** -```tomo ->> my_list.clear() -``` - ---- - -### `counts` -Counts the occurrences of each element in the list. - -```tomo -func counts(list: [T] -> {T=Int}) -``` - -- `list`: The list to count elements in. - -**Returns:** -A table mapping each element to its count. - -**Example:** -```tomo ->> [10, 20, 30, 30, 30].counts() -= {10=1, 20=1, 30=3} -``` - ---- - -### `find` -Finds the index of the first occurrence of an element (if any). - -```tomo -func find(list: [T], target: T -> Int?) -``` - -- `list`: The list to search through. -- `item`: The item to find in the list. - -**Returns:** -The index of the first occurrence or `!Int` if not found. - -**Example:** -```tomo ->> [10, 20, 30, 40, 50].find(20) -= 2 : Int? - ->> [10, 20, 30, 40, 50].find(9999) -= none : Int? -``` - ---- - -### `first` -Find the index of the first item that matches a predicate function (if any). - -```tomo -func first(list: [T], predicate: func(item:&T -> Bool) -> Int) -``` - -- `list`: The list to search through. -- `predicate`: A function that returns `yes` if the item should be returned or - `no` if it should not. - -**Returns:** -Returns the index of the first item where the predicate is true or `!Int` if no -item matches. - -**Example:** -```tomo ->> [4, 5, 6].find(func(i:&Int): i.is_prime()) -= 5 : Int? ->> [4, 6, 8].find(func(i:&Int): i.is_prime()) -= none : Int? -``` - ---- - -### `from` -Returns a slice of the list starting from a specified index. - -```tomo -func from(list: [T], first: Int -> [T]) -``` - -- `list`: The original list. -- `first`: The index to start from. - -**Returns:** -A new list starting from the specified index. - -**Example:** -```tomo ->> [10, 20, 30, 40, 50].from(3) -= [30, 40, 50] -``` - ---- - -### `has` -Checks if the list has an element. - -```tomo -func has(list: [T], element: T -> Bool) -``` - -- `list`: The list to check. -- `target`: The element to check for. - -**Returns:** -`yes` if the list has the target, `no` otherwise. - -**Example:** -```tomo ->> [10, 20, 30].has(20) -= yes -``` - ---- - -### `heap_pop` -Removes and returns the top element of a heap or `none` if the list is empty. -By default, this is the *minimum* value in the heap. - -```tomo -func heap_pop(list: @[T], by: func(x,y:&T->Int32) = T.compare -> T?) -``` - -- `list`: The mutable reference to the heap. -- `by`: The comparison function used to determine order. If not specified, the - default comparison function for the item type will be used. - -**Returns:** -The removed top element of the heap or `none` if the list is empty. - -**Example:** -```tomo ->> my_heap := [30, 10, 20] ->> my_heap.heapify() ->> my_heap.heap_pop() -= 10 -``` - ---- - -### `heap_push` -Adds an element to the heap and maintains the heap property. By default, this -is a *minimum* heap. - -```tomo -func heap_push(list: @[T], item: T, by=T.compare -> Void) -``` - -- `list`: The mutable reference to the heap. -- `item`: The item to be added. -- `by`: The comparison function used to determine order. If not specified, the - default comparison function for the item type will be used. - -**Returns:** -Nothing. - -**Example:** -```tomo ->> my_heap.heap_push(10) -``` - ---- - -### `heapify` -Converts a list into a heap. - -```tomo -func heapify(list: @[T], by: func(x,y:&T->Int32) = T.compare -> Void) -``` - -- `list`: The mutable reference to the list to be heapified. -- `by`: The comparison function used to determine order. If not specified, the - default comparison function for the item type will be used. - -**Returns:** -Nothing. - -**Example:** -```tomo ->> my_heap := [30, 10, 20] ->> my_heap.heapify() -``` - ---- - -### `insert` -Inserts an element at a specified position in the list. - -```tomo -func insert(list: @[T], item: T, at: Int = 0 -> Void) -``` - -- `list`: The mutable reference to the list. -- `item`: The item to be inserted. -- `at`: The index at which to insert the item (default is `0`). Since indices - are 1-indexed and negative indices mean "starting from the back", an index of - `0` means "after the last item". - -**Returns:** -Nothing. - -**Example:** -```tomo ->> list := [10, 20] ->> list.insert(30) ->> list -= [10, 20, 30] - ->> list.insert(999, at=2) ->> list -= [10, 999, 20, 30] -``` - ---- - -### `insert_all` -Inserts a list of items at a specified position in the list. - -```tomo -func insert_all(list: @[T], items: [T], at: Int = 0 -> Void) -``` - -- `list`: The mutable reference to the list. -- `items`: The items to be inserted. -- `at`: The index at which to insert the item (default is `0`). Since indices - are 1-indexed and negative indices mean "starting from the back", an index of - `0` means "after the last item". - -**Returns:** -Nothing. - -**Example:** -```tomo -list := [10, 20] -list.insert_all([30, 40]) ->> list -= [10, 20, 30, 40] - -list.insert_all([99, 100], at=2) ->> list -= [10, 99, 100, 20, 30, 40] -``` - ---- - -### `pop` -Removes and returns an item from the list. If the given index is present in -the list, the item at that index will be removed and the list will become one -element shorter. - -```tomo -func pop(list: &[T], index: Int = -1 -> T?) -``` - -- `list`: The list to remove an item from. -- `index`: The index from which to remove the item (default: the last item). - -**Returns:** -`none` if the list is empty or the given index does not exist in the list, -otherwise the item at the given index. - -**Example:** -```tomo ->> list := [10, 20, 30, 40] - ->> list.pop() -= 40 ->> list -= &[10, 20, 30] - ->> list.pop(index=2) -= 20 ->> list -= &[10, 30] -``` - ---- - -### `random` -Selects a random element from the list. - -```tomo -func random(list: [T], random: func(min,max:Int64->Int64)? = none -> T) -``` - -- `list`: The list from which to select a random element. -- `random`: If provided, this function will be used to get a random index in the list. Returned - values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number - generation) - -**Returns:** -A random element from the list. - -**Example:** -```tomo ->> [10, 20, 30].random() -= 20 -``` - ---- - -### `remove_at` -Removes elements from the list starting at a specified index. - -```tomo -func remove_at(list: @[T], at: Int = -1, count: Int = 1 -> Void) -``` - -- `list`: The mutable reference to the list. -- `at`: The index at which to start removing elements (default is `-1`, which means the end of the list). -- `count`: The number of elements to remove (default is `1`). - -**Returns:** -Nothing. - -**Example:** -```tomo -list := [10, 20, 30, 40, 50] -list.remove_at(2) ->> list -= [10, 30, 40, 50] - -list.remove_at(2, count=2) ->> list -= [10, 50] -``` - ---- - -### `remove_item` -Removes all occurrences of a specified item from the list. - -```tomo -func remove_item(list: @[T], item: T, max_count: Int = -1 -> Void) -``` - -- `list`: The mutable reference to the list. -- `item`: The item to be removed. -- `max_count`: The maximum number of occurrences to remove (default is `-1`, meaning all occurrences). - -**Returns:** -Nothing. - -**Example:** -```tomo -list := [10, 20, 10, 20, 30] -list.remove_item(10) ->> list -= [20, 20, 30] - -list.remove_item(20, max_count=1) ->> list -= [20, 30] -``` - ---- - -### `reversed` -Returns a reversed slice of the list. - -```tomo -func reversed(list: [T] -> [T]) -``` - -- `list`: The list to be reversed. - -**Returns:** -A slice of the list with elements in reverse order. - -**Example:** -```tomo ->> [10, 20, 30].reversed() -= [30, 20, 10] -``` - ---- - -### `sample` -Selects a sample of elements from the list, optionally with weighted -probabilities. - -```tomo -func sample(list: [T], count: Int, weights: [Num]? = ![Num], random: func(->Num)? = none -> [T]) -``` - -- `list`: The list to sample from. -- `count`: The number of elements to sample. -- `weights`: The probability weights for each element in the list. These - values do not need to add up to any particular number, they are relative - weights. If no weights are given, elements will be sampled with uniform - probability. -- `random`: If provided, this function will be used to get random values for - sampling the list. The provided function should return random numbers - between `0.0` (inclusive) and `1.0` (exclusive). (Used for deterministic - pseudorandom number generation) - -**Errors:** -Errors will be raised if any of the following conditions occurs: -- The given list has no elements and `count >= 1` -- `count < 0` (negative count) -- The number of weights provided doesn't match the length of the list. -- Any weight in the weights list is negative, infinite, or `NaN` -- The sum of the given weights is zero (zero probability for every element). - -**Returns:** -A list of sampled elements from the list. - -**Example:** -```tomo ->> [10, 20, 30].sample(2, weights=[90%, 5%, 5%]) -= [10, 10] -``` - ---- - -### `shuffle` -Shuffles the elements of the list in place. - -```tomo -func shuffle(list: @[T], random: func(min,max:Int64->Int64)? = none -> Void) -``` - -- `list`: The mutable reference to the list to be shuffled. -- `random`: If provided, this function will be used to get a random index in the list. Returned - values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number - generation) - -**Returns:** -Nothing. - -**Example:** -```tomo ->> list.shuffle() -``` - ---- - -### `shuffled` -Creates a new list with elements shuffled. - -```tomo -func shuffled(list: [T], random: func(min,max:Int64->Int64)? = none -> [T]) -``` - -- `list`: The list to be shuffled. -- `random`: If provided, this function will be used to get a random index in the list. Returned - values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number - generation) - -**Returns:** -A new list with shuffled elements. - -**Example:** -```tomo ->> [10, 20, 30, 40].shuffled() -= [40, 10, 30, 20] -``` - ---- - -### `slice` -Returns a slice of the list spanning the given indices (inclusive). - -```tomo -func slice(list: [T], from: Int, to: Int -> [T]) -``` - -- `list`: The original list. -- `from`: The first index to include. -- `to`: The last index to include. - -**Returns:** -A new list spanning the given indices. Note: negative indices are counted from -the back of the list, so `-1` refers to the last element, `-2` the -second-to-last, and so on. - -**Example:** -```tomo ->> [10, 20, 30, 40, 50].slice(2, 4) -= [20, 30, 40] - ->> [10, 20, 30, 40, 50].slice(-3, -2) -= [30, 40] -``` - ---- - -### `sort` -Sorts the elements of the list in place in ascending order (small to large). - -```tomo -func sort(list: @[T], by=T.compare -> Void) -``` - -- `list`: The mutable reference to the list to be sorted. -- `by`: The comparison function used to determine order. If not specified, the - default comparison function for the item type will be used. - -**Returns:** -Nothing. - -**Example:** -```tomo -list := [40, 10, -30, 20] -list.sort() ->> list -= [-30, 10, 20, 40] - -list.sort(func(a,b:&Int): a.abs() <> b.abs()) ->> list -= [10, 20, -30, 40] -``` - ---- - -### `sorted` -Creates a new list with elements sorted. - -```tomo -func sorted(list: [T], by=T.compare -> [T]) -``` - -- `list`: The list to be sorted. -- `by`: The comparison function used to determine order. If not specified, the - default comparison function for the item type will be used. - -**Returns:** -A new list with sorted elements. - -**Example:** -```tomo ->> [40, 10, -30, 20].sorted() -= [-30, 10, 20, 40] - ->> [40, 10, -30, 20].sorted(func(a,b:&Int): a.abs() <> b.abs()) -= [10, 20, -30, 40] -``` - ---- - -### `to` -Returns a slice of the list from the start of the original list up to a specified index (inclusive). - -```tomo -func to(list: [T], last: Int -> [T]) -``` - -- `list`: The original list. -- `last`: The index up to which elements should be included. - -**Returns:** -A new list containing elements from the start up to the specified index. - -**Example:** -```tomo ->> [10, 20, 30, 40, 50].to(3) -= [10, 20, 30] - ->> [10, 20, 30, 40, 50].to(-2) -= [10, 20, 30, 40] -``` - ---- - -### `unique` -Returns a Set that contains the unique elements of the list. - -```tomo -func unique(list: [T] -> |T|) -``` - -- `list`: The list to process. - -**Returns:** -A set containing only unique elements from the list. - -**Example:** -```tomo ->> [10, 20, 10, 10, 30].unique() -= {10, 20, 30} -``` +[API documentation](../api/lists.md) diff --git a/docs/nums.md b/docs/nums.md index c209d74d..1bd9b52d 100644 --- a/docs/nums.md +++ b/docs/nums.md @@ -94,1146 +94,6 @@ eliminating conditional branching inside of compound math expressions. Users should also be able to write code that can safely assume that all values provided are not NaN. -## Constants +# API -- **`1_PI`**: \( \frac{1}{\pi} \) -- **`2_PI`**: \( 2 \times \pi \) -- **`2_SQRTPI`**: \( 2 \times \sqrt{\pi} \) -- **`E`**: Base of natural logarithms (\( e \)) -- **`INF`**: Positive infinity -- **`LN10`**: Natural logarithm of 10 -- **`LN2`**: Natural logarithm of 2 -- **`LOG2E`**: Logarithm base 2 of \( e \) -- **`PI`**: Pi (\( \pi \)) -- **`PI_2`**: \( \frac{\pi}{2} \) -- **`PI_4`**: \( \frac{\pi}{4} \) -- **`SQRT1_2`**: \( \sqrt{\frac{1}{2}} \) -- **`SQRT2`**: \( \sqrt{2} \) -- **`TAU`**: Tau (\( 2 \times \pi \)) - -## Functions - -Each Num type has its own version of the following functions. Functions can be -called either on the type itself: `Num.sqrt(x)` or as a method call: -`x.sqrt()`. Method call syntax is preferred. - ---- - -- [`func abs(n: Num -> Num)`](#abs) -- [`func acos(x: Num -> Num)`](#acos) -- [`func acosh(x: Num -> Num)`](#acosh) -- [`func asin(x: Num -> Num)`](#asin) -- [`func asinh(x: Num -> Num)`](#asinh) -- [`func atan(x: Num -> Num)`](#atan) -- [`func atan2(x: Num, y: Num -> Num)`](#atan2) -- [`func atanh(x: Num -> Num)`](#atanh) -- [`func cbrt(x: Num -> Num)`](#cbrt) -- [`func ceil(x: Num -> Num)`](#ceil) -- [`func clamped(x, low, high: Num -> Num)`](#clamped) -- [`func copysign(x: Num, y: Num -> Num)`](#copysign) -- [`func cos(x: Num -> Num)`](#cos) -- [`func cosh(x: Num -> Num)`](#cosh) -- [`func erf(x: Num -> Num)`](#erf) -- [`func erfc(x: Num -> Num)`](#erfc) -- [`func exp(x: Num -> Num)`](#exp) -- [`func exp2(x: Num -> Num)`](#exp2) -- [`func expm1(x: Num -> Num)`](#expm1) -- [`func fdim(x: Num, y: Num -> Num)`](#fdim) -- [`func floor(x: Num -> Num)`](#floor) -- [`func format(n: Num, precision: Int = 0 -> Text)`](#format) -- [`func hypot(x: Num, y: Num -> Num)`](#hypot) -- [`func isfinite(n: Num -> Bool)`](#isfinite) -- [`func is_between(n: Num, low: Num, high: Num -> Bool)`](#is_between) -- [`func isinf(n: Num -> Bool)`](#isinf) -- [`func j0(x: Num -> Num)`](#j0) -- [`func j1(x: Num -> Num)`](#j1) -- [`func log(x: Num -> Num)`](#log) -- [`func log10(x: Num -> Num)`](#log10) -- [`func log1p(x: Num -> Num)`](#log1p) -- [`func log2(x: Num -> Num)`](#log2) -- [`func logb(x: Num -> Num)`](#logb) -- [`func mix(amount: Num, x: Num, y: Num -> Num)`](#mix) -- [`func near(x: Num, y: Num, ratio: Num = 1e-9, min_epsilon: Num = 1e-9 -> Bool)`](#near) -- [`func nextafter(x: Num, y: Num -> Num)`](#nextafter) -- [`func parse(text: Text -> Num?)`](#parse) -- [`func percent(n: Num -> Text)`](#percent) -- [`func rint(x: Num -> Num)`](#rint) -- [`func round(x: Num -> Num)`](#round) -- [`func scientific(n: Num, precision: Int = 0 -> Text)`](#scientific) -- [`func significand(x: Num -> Num)`](#significand) -- [`func sin(x: Num -> Num)`](#sin) -- [`func sinh(x: Num -> Num)`](#sinh) -- [`func sqrt(x: Num -> Num)`](#sqrt) -- [`func tan(x: Num -> Num)`](#tan) -- [`func tanh(x: Num -> Num)`](#tanh) -- [`func tgamma(x: Num -> Num)`](#tgamma) -- [`func trunc(x: Num -> Num)`](#trunc) -- [`func y0(x: Num -> Num)`](#y0) -- [`func y1(x: Num -> Num)`](#y1) - -### `abs` -Calculates the absolute value of a number. - -```tomo -func abs(n: Num -> Num) -``` - -- `n`: The number whose absolute value is to be computed. - -**Returns:** -The absolute value of `n`. - -**Example:** -```tomo ->> (-3.5).abs() -= 3.5 -``` - ---- - -### `acos` -Computes the arc cosine of a number. - -```tomo -func acos(x: Num -> Num) -``` - -- `x`: The number for which the arc cosine is to be calculated. - -**Returns:** -The arc cosine of `x` in radians. - -**Example:** -```tomo ->> (0.0).acos() // -> (π/2) -= 1.5708 -``` - ---- - -### `acosh` -Computes the inverse hyperbolic cosine of a number. - -```tomo -func acosh(x: Num -> Num) -``` - -- `x`: The number for which the inverse hyperbolic cosine is to be calculated. - -**Returns:** -The inverse hyperbolic cosine of `x`. - -**Example:** -```tomo ->> (1.0).acosh() -= 0 -``` - ---- - -### `asin` -Computes the arc sine of a number. - -```tomo -func asin(x: Num -> Num) -``` - -- `x`: The number for which the arc sine is to be calculated. - -**Returns:** -The arc sine of `x` in radians. - -**Example:** -```tomo ->> (0.5).asin() // -> (π/6) -= 0.5236 -``` - ---- - -### `asinh` -Computes the inverse hyperbolic sine of a number. - -```tomo -func asinh(x: Num -> Num) -``` - -- `x`: The number for which the inverse hyperbolic sine is to be calculated. - -**Returns:** -The inverse hyperbolic sine of `x`. - -**Example:** -```tomo ->> (0.0).asinh() -= 0 -``` - ---- - -### `atan` -Computes the arc tangent of a number. - -```tomo -func atan(x: Num -> Num) -``` - -- `x`: The number for which the arc tangent is to be calculated. - -**Returns:** -The arc tangent of `x` in radians. - -**Example:** -```tomo ->> (1.0).atan() // -> (π/4) -= 0.7854 -``` - ---- - -### `atan2` -Computes the arc tangent of the quotient of two numbers. - -```tomo -func atan2(x: Num, y: Num -> Num) -``` - -- `x`: The numerator. -- `y`: The denominator. - -**Returns:** -The arc tangent of `x/y` in radians. - -**Example:** -```tomo ->> Num.atan2(1, 1) // -> (π/4) -= 0.7854 -``` - ---- - -### `atanh` -Computes the inverse hyperbolic tangent of a number. - -```tomo -func atanh(x: Num -> Num) -``` - -- `x`: The number for which the inverse hyperbolic tangent is to be calculated. - -**Returns:** -The inverse hyperbolic tangent of `x`. - -**Example:** -```tomo ->> (0.5).atanh() -= 0.5493 -``` - ---- - -### `cbrt` -Computes the cube root of a number. - -```tomo -func cbrt(x: Num -> Num) -``` - -- `x`: The number for which the cube root is to be calculated. - -**Returns:** -The cube root of `x`. - -**Example:** -```tomo ->> (27.0).cbrt() -= 3 -``` - ---- - -### `ceil` -Rounds a number up to the nearest integer. - -```tomo -func ceil(x: Num -> Num) -``` - -- `x`: The number to be rounded up. - -**Returns:** -The smallest integer greater than or equal to `x`. - -**Example:** -```tomo ->> (3.2).ceil() -= 4 -``` - ---- - -### `clamped` -Returns the given number clamped between two values so that it is within -that range. - -```tomo -func clamped(x, low, high: Num -> Num) -``` - -- `x`: The number to clamp. -- `low`: The lowest value the result can take. -- `high`: The highest value the result can take. - -**Returns:** -The first argument clamped between the other two arguments. - -**Example:** -```tomo ->> (2.5).clamped(5.5, 10.5) -= 5.5 -``` - ---- - -### `copysign` -Copies the sign of one number to another. - -```tomo -func copysign(x: Num, y: Num -> Num) -``` - -- `x`: The number whose magnitude will be copied. -- `y`: The number whose sign will be copied. - -**Returns:** -A number with the magnitude of `x` and the sign of `y`. - -**Example:** -```tomo ->> (3.0).copysign(-1) -= -3 -``` - ---- - -### `cos` -Computes the cosine of a number (angle in radians). - -```tomo -func cos(x: Num -> Num) -``` - -- `x`: The angle in radians. - -**Returns:** -The cosine of `x`. - -**Example:** -```tomo ->> (0.0).cos() -= 1 -``` - ---- - -### `cosh` -Computes the hyperbolic cosine of a number. - -```tomo -func cosh(x: Num -> Num) -``` - -- `x`: The number for which the hyperbolic cosine is to be calculated. - -**Returns:** -The hyperbolic cosine of `x`. - -**Example:** -```tomo ->> (0.0).cosh() -= 1 -``` - ---- - -### `erf` -Computes the error function of a number. - -```tomo -func erf(x: Num -> Num) -``` - -- `x`: The number for which the error function is to be calculated. - -**Returns:** -The error function of `x`. - -**Example:** -```tomo ->> (0.0).erf() -= 0 -``` - ---- - -### `erfc` -Computes the complementary error function of a number. - -```tomo -func erfc(x: Num -> Num) -``` - -- `x`: The number for which the complementary error function is to be calculated. - -**Returns:** -The complementary error function of `x`. - -**Example:** -```tomo ->> (0.0).erfc() -= 1 -``` - ---- - -### `exp` -Computes the exponential function \( e^x \) for a number. - -```tomo -func exp(x: Num -> Num) -``` - -- `x`: The exponent. - -**Returns:** -The value of \( e^x \). - -**Example:** -```tomo ->> (1.0).exp() -= 2.7183 -``` - ---- - -### `exp2` -Computes \( 2^x \) for a number. - -```tomo -func exp2(x: Num -> Num) -``` - -- `x`: The exponent. - -**Returns:** -The value of \( 2^x \). - -**Example:** -```tomo ->> (3.0).exp2() -= 8 -``` - ---- - -### `expm1` -Computes \( e^x - 1 \) for a number. - -```tomo -func expm1(x: Num -> Num) -``` - -- `x`: The exponent. - -**Returns:** -The value of \( e^x - 1 \). - -**Example:** -```tomo ->> (1.0).expm1() -= 1.7183 -``` - ---- - -### `fdim` -Computes the positive difference between two numbers. - -```tomo -func fdim(x: Num, y: Num -> Num) -``` - -- `x`: The first number. -- `y`: The second number. - -**Returns:** -The positive difference \( \max(0, x - y) \). - -**Example:** -```tomo -fd - ->> (5.0).fdim(3) -= 2 -``` - ---- - -### `floor` -Rounds a number down to the nearest integer. - -```tomo -func floor(x: Num -> Num) -``` - -- `x`: The number to be rounded down. - -**Returns:** -The largest integer less than or equal to `x`. - -**Example:** -```tomo ->> (3.7).floor() -= 3 -``` - ---- - -### `format` -Formats a number as a text with a specified precision. - -```tomo -func format(n: Num, precision: Int = 0 -> Text) -``` - -- `n`: The number to be formatted. -- `precision`: The number of decimal places. Default is `0`. - -**Returns:** -A text representation of the number with the specified precision. - -**Example:** -```tomo ->> (3.14159).format(precision=2) -= "3.14" -``` - ---- - -### `hypot` -Computes the Euclidean norm, \( \sqrt{x^2 + y^2} \), of two numbers. - -```tomo -func hypot(x: Num, y: Num -> Num) -``` - -- `x`: The first number. -- `y`: The second number. - -**Returns:** -The Euclidean norm of `x` and `y`. - -**Example:** -```tomo ->> Num.hypot(3, 4) -= 5 -``` - ---- - -### `isfinite` -Checks if a number is finite. - -```tomo -func isfinite(n: Num -> Bool) -``` - -- `n`: The number to be checked. - -**Returns:** -`yes` if `n` is finite, `no` otherwise. - -**Example:** -```tomo ->> (1.0).isfinite() -= yes ->> Num.INF.isfinite() -= no -``` - ---- - -### `is_between` -Determines if a number is between two numbers (inclusive). - -```tomo -func is_between(x: Num, low: Num, high: Num -> Bool) -``` - -- `x`: The integer to be checked. -- `low`: The lower bound to check (inclusive). -- `high`: The upper bound to check (inclusive). - -**Returns:** -`yes` if `low <= x and x <= high`, otherwise `no` - -**Example:** -```tomo ->> (7.5).is_between(1, 10) -= yes ->> (7.5).is_between(100, 200) -= no ->> (7.5).is_between(1, 7.5) -= yes -``` - ---- - -### `isinf` -Checks if a number is infinite. - -```tomo -func isinf(n: Num -> Bool) -``` - -- `n`: The number to be checked. - -**Returns:** -`yes` if `n` is infinite, `no` otherwise. - -**Example:** -```tomo ->> Num.INF.isinf() -= yes ->> (1.0).isinf() -= no -``` - ---- - -### `j0` -Computes the Bessel function of the first kind of order 0. - -```tomo -func j0(x: Num -> Num) -``` - -- `x`: The number for which the Bessel function is to be calculated. - -**Returns:** -The Bessel function of the first kind of order 0 of `x`. - -**Example:** -```tomo ->> (0.0).j0() -= 1 -``` - ---- - -### `j1` -Computes the Bessel function of the first kind of order 1. - -```tomo -func j1(x: Num -> Num) -``` - -- `x`: The number for which the Bessel function is to be calculated. - -**Returns:** -The Bessel function of the first kind of order 1 of `x`. - -**Example:** -```tomo ->> (0.0).j1() -= 0 -``` - ---- - -### `log` -Computes the natural logarithm (base \( e \)) of a number. - -```tomo -func log(x: Num -> Num) -``` - -- `x`: The number for which the natural logarithm is to be calculated. - -**Returns:** -The natural logarithm of `x`. - -**Example:** -```tomo ->> Num.E.log() -= 1 -``` - ---- - -### `log10` -Computes the base-10 logarithm of a number. - -```tomo -func log10(x: Num -> Num) -``` - -- `x`: The number for which the base-10 logarithm is to be calculated. - -**Returns:** -The base-10 logarithm of `x`. - -**Example:** -```tomo ->> (100.0).log10() -= 2 -``` - ---- - -### `log1p` -Computes \( \log(1 + x) \) for a number. - -```tomo -func log1p(x: Num -> Num) -``` - -- `x`: The number for which \( \log(1 + x) \) is to be calculated. - -**Returns:** -The value of \( \log(1 + x) \). - -**Example:** -```tomo ->> (1.0).log1p() -= 0.6931 -``` - ---- - -### `log2` -Computes the base-2 logarithm of a number. - -```tomo -func log2(x: Num -> Num) -``` - -- `x`: The number for which the base-2 logarithm is to be calculated. - -**Returns:** -The base-2 logarithm of `x`. - -**Example:** -```tomo ->> (8.0).log2() -= 3 -``` - ---- - -### `logb` -Computes the binary exponent (base-2 logarithm) of a number. - -```tomo -func logb(x: Num -> Num) -``` - -- `x`: The number for which the binary exponent is to be calculated. - -**Returns:** -The binary exponent of `x`. - -**Example:** -```tomo ->> (8.0).logb() -= 3 -``` - ---- - -### `mix` -Interpolates between two numbers based on a given amount. - -```tomo -func mix(amount: Num, x: Num, y: Num -> Num) -``` - -- `amount`: The interpolation factor (between `0` and `1`). -- `x`: The starting number. -- `y`: The ending number. - -**Returns:** -The interpolated number between `x` and `y` based on `amount`. - -**Example:** -```tomo ->> (0.5).mix(10, 20) -= 15 ->> (0.25).mix(10, 20) -= 12.5 -``` - ---- - -### `near` -Checks if two numbers are approximately equal within specified tolerances. If -two numbers are within an absolute difference or the ratio between the two is -small enough, they are considered near each other. - -```tomo -func near(x: Num, y: Num, ratio: Num = 1e-9, min_epsilon: Num = 1e-9 -> Bool) -``` - -- `x`: The first number. -- `y`: The second number. -- `ratio`: The relative tolerance. Default is `1e-9`. -- `min_epsilon`: The absolute tolerance. Default is `1e-9`. - -**Returns:** -`yes` if `x` and `y` are approximately equal within the specified tolerances, `no` otherwise. - -**Example:** -```tomo ->> (1.0).near(1.000000001) -= yes - ->> (100.0).near(110, ratio=0.1) -= yes - ->> (5.0).near(5.1, min_epsilon=0.1) -= yes -``` - ---- - -### `nextafter` -Computes the next representable value after a given number towards a specified direction. - -```tomo -func nextafter(x: Num, y: Num -> Num) -``` - -- `x`: The starting number. -- `y`: The direction towards which to find the next representable value. - -**Returns:** -The next representable value after `x` in the direction of `y`. - -**Example:** -```tomo ->> (1.0).nextafter(1.1) -= 1.0000000000000002 -``` - ---- - -### `parse` -Converts a text representation of a number into a floating-point number. - -```tomo -func parse(text: Text -> Num?) -``` - -- `text`: The text containing the number. - -**Returns:** -The number represented by the text or `none` if the entire text can't be parsed -as a number. - -**Example:** -```tomo ->> Num.parse("3.14") -= 3.14 ->> Num.parse("1e3") -= 1000 -``` - ---- - -### `percent` -Convert a number into a percentage text with a percent sign. - -```tomo -func percent(n: Num, precision: Int = 0 -> Text) -``` - -- `n`: The number to be converted to a percent. -- `precision`: The number of decimal places. Default is `0`. - -**Returns:** -A text representation of the number as a percentage with a percent sign. - -**Example:** -```tomo ->> (0.5).percent() -= "50%" ->> (1./3.).percent(2) -= "33.33%" -``` - ---- - -### `rint` -Rounds a number to the nearest integer, with ties rounded to the nearest even integer. - -```tomo -func rint(x: Num -> Num) -``` - -- `x`: The number to be rounded. - -**Returns:** -The nearest integer value of `x`. - -**Example:** -```tomo ->> (3.5).rint() -= 4 ->> (2.5).rint() -= 2 -``` - ---- - -### `round` -Rounds a number to the nearest whole number integer. - -```tomo -func round(x: Num -> Num) -``` - -- `x`: The number to be rounded. - -**Returns:** -The nearest integer value of `x`. - -**Example:** -```tomo ->> (2.3).round() -= 2 ->> (2.7).round() -= 3 -``` - ---- - -### `scientific` -Formats a number in scientific notation with a specified precision. - -```tomo -func scientific(n: Num, precision: Int = 0 -> Text) -``` - -- `n`: The number to be formatted. -- `precision`: The number of decimal places. Default is `0`. - -**Returns:** -A text representation of the number in scientific notation with the specified precision. - -**Example:** -```tomo ->> (12345.6789).scientific(precision=2) -= "1.23e+04" -``` - ---- - -### `significand` -Extracts the significand (or mantissa) of a number. - -```tomo -func significand(x: Num -> Num) -``` - -- `x`: The number from which to extract the significand. - -**Returns:** -The significand of `x`. - -**Example:** -```tomo ->> (1234.567).significand() -= 0.1234567 -``` - ---- - -### `sin` -Computes the sine of a number (angle in radians). - -```tomo -func sin(x: Num -> Num) -``` - -- `x`: The angle in radians. - -**Returns:** -The sine of `x`. - -**Example:** -```tomo ->> (0.0).sin() -= 0 -``` - ---- - -### `sinh` -Computes the hyperbolic sine of a number. - -```tomo -func sinh(x: Num -> Num) -``` - -- `x`: The number for which the hyperbolic sine is to be calculated. - -**Returns:** -The hyperbolic sine of `x`. - -**Example:** -```tomo ->> (0.0).sinh() -= 0 -``` - ---- - -### `sqrt` -Computes the square root of a number. - -```tomo -func sqrt(x: Num -> Num) -``` - -- `x`: The number for which the square root is to be calculated. - -**Returns:** -The square root of `x`. - -**Example:** -```tomo ->> (16.0).sqrt() -= 4 -``` - ---- - -### `tan` -Computes the tangent of a number (angle in radians). - -```tomo -func tan(x: Num -> Num) -``` - -- `x`: The angle in radians. - -**Returns:** -The tangent of `x`. - -**Example:** -```tomo ->> (0.0).tan() -= 0 -``` - ---- - -### `tanh` -Computes the hyperbolic tangent of a number. - -```tomo -func tanh(x: Num -> Num) -``` - -- `x`: The number for which the hyperbolic tangent is to be calculated. - -**Returns:** -The hyperbolic tangent of `x`. - -**Example:** -```tomo ->> (0.0).tanh() -= 0 -``` - ---- - -### `tgamma` -Computes the gamma function of a number. - -```tomo -func tgamma(x: Num -> Num) -``` - -- `x`: The number for which the gamma function is to be calculated. - -**Returns:** -The gamma function of `x`. - -**Example:** -```tomo ->> (1.0).tgamma() -= 1 -``` - ---- - -### `trunc` -Truncates a number to the nearest integer towards zero. - -```tomo -func trunc(x: Num -> Num) -``` - -- `x`: The number to be truncated. - -**Returns:** -The integer part of `x` towards zero. - -**Example:** -```tomo ->> (3.7).trunc() -= 3 ->> (-3.7).trunc() -= -3 -``` - ---- - -### `y0` -Computes the Bessel function of the second kind of order 0. - -```tomo -func y0(x: Num -> Num) -``` - -- `x`: The number for which the Bessel function is to be calculated. - -**Returns:** -The Bessel function of the second kind of order 0 of `x`. - -**Example:** -```tomo ->> (1.0).y0() -= -0.7652 -``` - ---- - -### `y1` -Computes the Bessel function of the second kind of order 1. - -```tomo -func y1(x: Num -> Num) -``` - -- `x`: The number for which the Bessel function is to be calculated. - -**Returns:** -The Bessel function of the second kind of order 1 of `x`. - -**Example:** -```tomo ->> (1.0).y1() -= 0.4401 -``` +[API documentation](../api/nums.md) diff --git a/docs/paths.md b/docs/paths.md index 6cf986a7..2fa55b13 100644 --- a/docs/paths.md +++ b/docs/paths.md @@ -35,967 +35,6 @@ i.e. the name of a directory or file. If a user were to supply a value like intended. Paths can be created from text with slashes using `Path.from_text(text)` if you need to use arbitrary text as a file path. -## Path Methods +# API -- [`func accessed(path:Path, follow_symlinks=yes -> Int64?)`](#accessed) -- [`func append(path: Path, text: Text, permissions: Int32 = 0o644[32] -> Void)`](#append) -- [`func append_bytes(path: Path, bytes: [Byte], permissions: Int32 = 0o644[32] -> Void)`](#append_bytes) -- [`func base_name(path: Path -> Text)`](#base_name) -- [`func by_line(path: Path -> func(->Text?)?)`](#by_line) -- [`func can_execute(path:Path -> Bool)`](#can_execute) -- [`func can_read(path:Path -> Bool)`](#can_read) -- [`func can_write(path:Path -> Bool)`](#can_write) -- [`func changed(path:Path, follow_symlinks=yes -> Int64?)`](#changed) -- [`func child(path: Path, child:Text -> Path)`](#child) -- [`func children(path: Path, include_hidden=no -> [Path])`](#children) -- [`func create_directory(path: Path, permissions=0o755[32] -> Void)`](#create_directory) -- [`func current_dir(-> Path)`](#current_dir) -- [`func exists(path: Path -> Bool)`](#exists) -- [`func expand_home(path: Path -> Path)`](#expand_home) -- [`func extension(path: Path, full=yes -> Text)`](#extension) -- [`func files(path: Path, include_hidden=no -> [Path])`](#files) -- [`func from_components(components:[Text] -> Path)`](#from_components) -- [`func glob(path: Path -> [Path])`](#glob) -- [`func group(path: Path, follow_symlinks=yes -> Text?)`](#group) -- [`func is_directory(path: Path, follow_symlinks=yes -> Bool)`](#is_directory) -- [`func is_file(path: Path, follow_symlinks=yes -> Bool)`](#is_file) -- [`func is_socket(path: Path, follow_symlinks=yes -> Bool)`](#is_socket) -- [`func is_symlink(path: Path -> Bool)`](#is_symlink) -- [`func modified(path:Path, follow_symlinks=yes -> Int64?)`](#modified) -- [`func owner(path: Path, follow_symlinks=yes -> Text?)`](#owner) -- [`func parent(path: Path -> Path)`](#parent) -- [`func read(path: Path -> Text?)`](#read) -- [`func read_bytes(path: Path, limit: Int? = none -> [Byte]?)`](#read_bytes) -- [`func relative_to(path: Path, relative_to=(./) -> Path)`](#relative_to) -- [`func remove(path: Path, ignore_missing=no -> Void)`](#remove) -- [`func resolved(path: Path, relative_to=(./) -> Path)`](#resolved) -- [`func set_owner(path:Path, owner:Text?=none, group:Text?=none, follow_symlinks=yes)`](#set_owner) -- [`func subdirectories(path: Path, include_hidden=no -> [Path])`](#subdirectories) -- [`func unique_directory(path: Path -> Path)`](#unique_directory) -- [`func write(path: Path, text: Text, permissions=0o644[32] -> Void)`](#write) -- [`func write_bytes(path: Path, bytes: [Byte], permissions=0o644[32] -> Void)`](#write_bytes) -- [`func write_unique(path: Path, text: Text -> Path)`](#write_unique) -- [`func write_unique_bytes(path: Path, bytes: [Byte] -> Path)`](#write_unique_bytes) - -### `accessed` -Gets the file access time of a file. - -```tomo -func accessed(path:Path, follow_symlinks: Bool = yes -> Int64?) -``` - -- `path`: The path of the file whose access time you want. -- `follow_symlinks`: Whether to follow symbolic links (default is `yes`). - -**Returns:** -A 64-bit unix epoch timestamp representing when the file or directory was last -accessed, or `none` if no such file or directory exists. - -**Example:** -```tomo ->> (./file.txt).accessed() -= 1704221100? ->> (./not-a-file).accessed() -= none -``` - ---- - -### `append` -Appends the given text to the file at the specified path, creating the file if -it doesn't already exist. Failure to write will result in a runtime error. - -```tomo -func append(path: Path, text: Text, permissions: Int32 = 0o644[32] -> Void) -``` - -- `path`: The path of the file to append to. -- `text`: The text to append to the file. -- `permissions`: The permissions to set on the file if it is being created (default is `0o644`). - -**Returns:** -Nothing. - -**Example:** -```tomo -(./log.txt).append("extra line$(\n)") -``` - ---- - -### `append_bytes` -Appends the given bytes to the file at the specified path, creating the file if -it doesn't already exist. Failure to write will result in a runtime error. - -```tomo -func append_bytes(path: Path, bytes: [Byte], permissions: Int32 = 0o644[32] -> Void) -``` - -- `path`: The path of the file to append to. -- `bytes`: The bytes to append to the file. -- `permissions`: The permissions to set on the file if it is being created (default is `0o644`). - -**Returns:** -Nothing. - -**Example:** -```tomo -(./log.txt).append_bytes([104[B], 105[B]]) -``` - ---- - -### `base_name` -Returns the base name of the file or directory at the specified path. - -```tomo -func base_name(path: Path -> Text) -``` - -- `path`: The path of the file or directory. - -**Returns:** -The base name of the file or directory. - -**Example:** -```tomo ->> (./path/to/file.txt).base_name() -= "file.txt" -``` - ---- - -### `by_line` -Returns an iterator that can be used to iterate over a file one line at a time, -or returns a null value if the file could not be opened. - -```tomo -func by_line(path: Path -> func(->Text?)?) -``` - -- `path`: The path of the file. - -**Returns:** -An iterator that can be used to get lines from a file one at a time or a null -value if the file couldn't be read. - -**Example:** -```tomo -# Safely handle file not being readable: -if lines := (./file.txt).by_line() - for line in lines - say(line.upper()) -else - say("Couldn't read file!") - -# Assume the file is readable and error if that's not the case: -for line in (/dev/stdin).by_line()! - say(line.upper()) -``` - ---- - -### `can_execute` -Returns whether or not a file can be executed by the current user/group. - -```tomo -func can_execute(path: Path -> Bool) -``` - -- `path`: The path of the file to check. - -**Returns:** -`yes` if the file or directory exists and the current user has execute permissions, otherwise `no`. - -**Example:** -```tomo ->> (/bin/sh).can_execute() -= yes ->> (/usr/include/stdlib.h).can_execute() -= no ->> (/non/existant/file).can_execute() -= no -``` - ---- - -### `can_read` -Returns whether or not a file can be read by the current user/group. - -```tomo -func can_read(path: Path -> Bool) -``` - -- `path`: The path of the file to check. - -**Returns:** -`yes` if the file or directory exists and the current user has read permissions, otherwise `no`. - -**Example:** -```tomo ->> (/usr/include/stdlib.h).can_read() -= yes ->> (/etc/shadow).can_read() -= no ->> (/non/existant/file).can_read() -= no -``` - ---- - -### `can_write` -Returns whether or not a file can be written by the current user/group. - -```tomo -func can_write(path: Path -> Bool) -``` - -- `path`: The path of the file to check. - -**Returns:** -`yes` if the file or directory exists and the current user has write permissions, otherwise `no`. - -**Example:** -```tomo ->> (/tmp).can_write() -= yes ->> (/etc/passwd).can_write() -= no ->> (/non/existant/file).can_write() -= no -``` - ---- - -### `changed` -Gets the file change time of a file. - -**Note:** this is the -["ctime"](https://en.wikipedia.org/wiki/Stat_(system_call)#ctime) of a file, -which is _not_ the file creation time. - -```tomo -func changed(path:Path, follow_symlinks: Bool = yes -> Int64?) -``` - -- `path`: The path of the file whose change time you want. -- `follow_symlinks`: Whether to follow symbolic links (default is `yes`). - -**Returns:** -A 64-bit unix epoch timestamp representing when the file or directory was last -changed, or `none` if no such file or directory exists. - -**Example:** -```tomo ->> (./file.txt).changed() -= 1704221100? ->> (./not-a-file).changed() -= none -``` - ---- - -### `child` -Return a path that is a child of another path. - -```tomo -func child(path: Path, child: Text -> [Path]) -``` - -- `path`: The path of a directory. -- `child`: The name of a child file or directory. - -**Returns:** -A new path representing the child. - -**Example:** -```tomo ->> (./directory).child("file.txt") -= (./directory/file.txt) -``` - ---- - -### `children` -Returns a list of children (files and directories) within the directory at the specified path. Optionally includes hidden files. - -```tomo -func children(path: Path, include_hidden=no -> [Path]) -``` - -- `path`: The path of the directory. -- `include_hidden`: Whether to include hidden files, which start with a `.` (default is `no`). - -**Returns:** -A list of paths for the children. - -**Example:** -```tomo ->> (./directory).children(include_hidden=yes) -= [".git", "foo.txt"] -``` - ---- - -### `create_directory` -Creates a new directory at the specified path with the given permissions. If -any of the parent directories do not exist, they will be created as needed. - -```tomo -func create_directory(path: Path, permissions=0o755[32] -> Void) -``` - -- `path`: The path of the directory to create. -- `permissions`: The permissions to set on the new directory (default is `0o644`). - -**Returns:** -Nothing. - -**Example:** -```tomo -(./new_directory).create_directory() -``` - ---- - -### `current_dir` -Creates a new directory at the specified path with the given permissions. If -any of the parent directories do not exist, they will be created as needed. - -```tomo -func current_dir(-> Path) -``` - -**Returns:** -The absolute path of the current directory. - -**Example:** -```tomo ->> Path.current_dir() -= (/home/user/tomo) -``` - ---- - -### `exists` -Checks if a file or directory exists at the specified path. - -```tomo -func exists(path: Path -> Bool) -``` - -- `path`: The path to check. - -**Returns:** -`True` if the file or directory exists, `False` otherwise. - -**Example:** -```tomo ->> (/).exists() -= yes -``` - ---- - -### `expand_home` -For home-based paths (those starting with `~`), expand the path to replace the -tilde with and absolute path to the user's `$HOME` directory. - -```tomo -func expand_home(path: Path -> Path) -``` - -- `path`: The path to expand. - -**Returns:** -If the path does not start with a `~`, then return it unmodified. Otherwise, -replace the `~` with an absolute path to the user's home directory. - -**Example:** -```tomo ->> (~/foo).expand_home() # Assume current user is 'user' -= /home/user/foo ->> (/foo).expand_home() # No change -= /foo -``` - ---- - -### `extension` -Returns the file extension of the file at the specified path. Optionally returns the full extension. - -```tomo -func extension(path: Path, full:Bool = yes -> Text) -``` - -- `path`: The path of the file. -- `full`: Whether to return everything after the first `.` in the - base name, or only the last part of the extension (default is `yes`). - -**Returns:** -The file extension (not including the leading `.`) or an empty text if there is -no file extension. - -**Example:** -```tomo ->> (./file.tar.gz).extension() -= "tar.gz" ->> (./file.tar.gz).extension(full=no) -= "gz" ->> (/foo).extension() -= "" ->> (./.git).extension() -= "" -``` - ---- - -### `files` -Returns a list of files within the directory at the specified path. Optionally includes hidden files. - -```tomo -func files(path: Path, include_hidden: Bool = no -> [Path]) -``` - -- `path`: The path of the directory. -- `include_hidden`: Whether to include hidden files (default is `no`). - -**Returns:** -A list of file paths. - -**Example:** -```tomo ->> (./directory).files(include_hidden=yes) -= [(./directory/file1.txt), (./directory/file2.txt)] -``` - ---- - -### `from_components` -Returns a path built from a list of path components. - -```tomo -func from_components(components: [Text] -> Path) -``` - -- `components`: A list of path components. - -**Returns:** -A path representing the given components. - -**Example:** -```tomo ->> Path.from_components(["/", "usr", "include"]) -= /usr/include ->> Path.from_components(["foo.txt"]) -= ./foo.txt ->> Path.from_components(["~", ".local"]) -= ~/.local -``` - ---- - -### `glob` -Perform a globbing operation and return a list of matching paths. Some glob -specific details: - -- The paths "." and ".." are *not* included in any globbing results. -- Files or directories that begin with "." will not match `*`, but will match `.*`. -- Globs do support `{a,b}` syntax for matching files that match any of several - choices of patterns. -- The shell-style syntax `**` for matching subdirectories is not supported. - -```tomo -func glob(path: Path -> [Path]) -``` - -- `path`: The path of the directory which may contain special globbing characters - like `*`, `?`, or `{...}` - -**Returns:** -A list of file paths that match the glob. - -**Example:** -```tomo -# Current directory includes: foo.txt, baz.txt, qux.jpg, .hidden ->> (./*).glob() -= [(./foo.txt), (./baz.txt), (./qux.jpg)] - ->> (./*.txt).glob() -= [(./foo.txt), (./baz.txt)] - ->> (./*.{txt,jpg}).glob() -= [(./foo.txt), (./baz.txt), (./qux.jpg)] - ->> (./.*).glob() -= [(./.hidden)] - -# Globs with no matches return an empty list: ->> (./*.xxx).glob() -= [] -``` - ---- - -### `group` -Get the owning group of a file or directory. - -```tomo -func group(path: Path, follow_symlinks: Bool = yes -> Text?) -``` - -- `path`: The path whose owning group to get. -- `follow_symlinks`: Whether to follow symbolic links (default is `yes`). - -**Returns:** -The name of the group which owns the file or directory, or `none` if the path does not exist. - -**Example:** -```tomo ->> (/bin).group() -= "root" ->> (/non/existent/file).group() -= none -``` - ---- - -### `is_directory` -Checks if the path represents a directory. Optionally follows symbolic links. - -```tomo -func is_directory(path: Path, follow_symlinks=yes -> Bool) -``` - -- `path`: The path to check. -- `follow_symlinks`: Whether to follow symbolic links (default is `yes`). - -**Returns:** -`True` if the path is a directory, `False` otherwise. - -**Example:** -```tomo ->> (./directory/).is_directory() -= yes - ->> (./file.txt).is_directory() -= no -``` - ---- - -### `is_file` -Checks if the path represents a file. Optionally follows symbolic links. - -```tomo -func is_file(path: Path, follow_symlinks=yes -> Bool) -``` - -- `path`: The path to check. -- `follow_symlinks`: Whether to follow symbolic links (default is `yes`). - -**Returns:** -`True` if the path is a file, `False` otherwise. - -**Example:** -```tomo ->> (./file.txt).is_file() -= yes - ->> (./directory/).is_file() -= no -``` - ---- - -### `is_socket` -Checks if the path represents a socket. Optionally follows symbolic links. - -```tomo -func is_socket(path: Path, follow_symlinks=yes -> Bool) -``` - -- `path`: The path to check. -- `follow_symlinks`: Whether to follow symbolic links (default is `yes`). - -**Returns:** -`True` if the path is a socket, `False` otherwise. - -**Example:** -```tomo ->> (./socket).is_socket() -= yes -``` - ---- - -### `is_symlink` -Checks if the path represents a symbolic link. - -```tomo -func is_symlink(path: Path -> Bool) -``` - -- `path`: The path to check. - -**Returns:** -`True` if the path is a symbolic link, `False` otherwise. - -**Example:** -```tomo ->> (./link).is_symlink() -= yes -``` - ---- - -### `modified` -Gets the file modification time of a file. - -```tomo -func modified(path:Path, follow_symlinks: Bool = yes -> Int64?) -``` - -- `path`: The path of the file whose modification time you want. -- `follow_symlinks`: Whether to follow symbolic links (default is `yes`). - -**Returns:** -A 64-bit unix epoch timestamp representing when the file or directory was last -modified, or `none` if no such file or directory exists. - -**Example:** -```tomo ->> (./file.txt).modified() -= 1704221100? ->> (./not-a-file).modified() -= none -``` - ---- - -### `owner` -Get the owning user of a file or directory. - -```tomo -func owner(path: Path, follow_symlinks: Bool = yes -> Text?) -``` - -- `path`: The path whose owner to get. -- `follow_symlinks`: Whether to follow symbolic links (default is `yes`). - -**Returns:** -The name of the user who owns the file or directory, or `none` if the path does not exist. - -**Example:** -```tomo ->> (/bin).owner() -= "root" ->> (/non/existent/file).owner() -= none -``` - ---- - -### `parent` -Returns the parent directory of the file or directory at the specified path. - -```tomo -func parent(path: Path -> Path) -``` - -- `path`: The path of the file or directory. - -**Returns:** -The path of the parent directory. - -**Example:** -```tomo ->> (./path/to/file.txt).parent() -= (./path/to/) -``` - ---- - -### `read` -Reads the contents of the file at the specified path or a null value if the -file could not be read. - -```tomo -func read(path: Path -> Text?) -``` - -- `path`: The path of the file to read. - -**Returns:** -The contents of the file. If the file could not be read, a null value will be -returned. If the file can be read, but is not valid UTF8 data, an error will be -raised. - -**Example:** -```tomo ->> (./hello.txt).read() -= "Hello"? - ->> (./nosuchfile.xxx).read() -= none -``` ---- - -### `read_bytes` -Reads the contents of the file at the specified path or a null value if the -file could not be read. - -```tomo -func read_bytes(path: Path, limit: Int? = none -> [Byte]?) -``` - -- `path`: The path of the file to read. -- `limit`: A limit to how many bytes should be read. - -**Returns:** -The byte contents of the file. If the file cannot be read, a null value will be -returned. - -**Example:** -```tomo ->> (./hello.txt).read() -= [72[B], 101[B], 108[B], 108[B], 111[B]]? - ->> (./nosuchfile.xxx).read() -= none -``` - ---- - -### `relative_to` -Returns the path relative to a given base path. By default, the base path is the current directory. - -```tomo -func relative_to(path: Path, relative_to=(./) -> Path) -``` - -- `path`: The path to convert. -- `relative_to`: The base path for the relative path (default is `./`). - -**Returns:** -The relative path. - -**Example:** -```tomo ->> (./path/to/file.txt).relative(relative_to=(./path)) -= (./to/file.txt) -``` - ---- - -### `remove` -Removes the file or directory at the specified path. A runtime error is raised if something goes wrong. - -```tomo -func remove(path: Path, ignore_missing=no -> Void) -``` - -- `path`: The path to remove. -- `ignore_missing`: Whether to ignore errors if the file or directory does not exist (default is `no`). - -**Returns:** -Nothing. - -**Example:** -```tomo -(./file.txt).remove() -``` - ---- - -### `resolved` -Resolves the absolute path of the given path relative to a base path. By default, the base path is the current directory. - -```tomo -func resolved(path: Path, relative_to=(./) -> Path) -``` - -- `path`: The path to resolve. -- `relative_to`: The base path for resolution (default is `./`). - -**Returns:** -The resolved absolute path. - -**Example:** -```tomo ->> (~/foo).resolved() -= (/home/user/foo) - ->> (./path/to/file.txt).resolved(relative_to=(/foo)) -= (/foo/path/to/file.txt) -``` - ---- - -### `set_owner` -Set the owning user and/or group for a path. - -```tomo -func set_owner(path:Path, owner: Text? = none, group: Text? = none, follow_symlinks: Bool = yes) -``` - -- `path`: The path to change the permissions for. -- `owner`: If non-none, the new user to assign to be the owner of the file (default: `none`). -- `group`: If non-none, the new group to assign to be the owner of the file (default: `none`). -- `follow_symlinks`: Whether to follow symbolic links (default is `yes`). - -**Returns:** -Nothing. If a path does not exist, a failure will be raised. - -**Example:** -```tomo -(./file.txt).set_owner(owner="root", group="wheel") -``` - ---- - -### `subdirectories` -Returns a list of subdirectories within the directory at the specified path. Optionally includes hidden subdirectories. - -```tomo -func subdirectories(path: Path, include_hidden=no -> [Path]) -``` - -- `path`: The path of the directory. -- `include_hidden`: Whether to include hidden subdirectories (default is `no`). - -**Returns:** -A list of subdirectory paths. - -**Example:** -```tomo ->> (./directory).subdirectories() -= [(./directory/subdir1), (./directory/subdir2)] - ->> (./directory).subdirectories(include_hidden=yes) -= [(./directory/.git), (./directory/subdir1), (./directory/subdir2)] -``` - ---- - -### `unique_directory` -Generates a unique directory path based on the given path. Useful for creating temporary directories. - -```tomo -func unique_directory(path: Path -> Path) -``` - -- `path`: The base path for generating the unique directory. The last six letters of this path must be `XXXXXX`. - -**Returns:** -A unique directory path after creating the directory. - -**Example:** - -``` ->> created := (/tmp/my-dir.XXXXXX).unique_directory() -= (/tmp/my-dir-AwoxbM/) ->> created.is_directory() -= yes -created.remove() -``` - ---- - -### `write` -Writes the given text to the file at the specified path, creating the file if -it doesn't already exist. Sets the file permissions as specified. If the file -writing cannot be successfully completed, a runtime error is raised. - -```tomo -func write(path: Path, text: Text, permissions=0o644[32] -> Void) -``` - -- `path`: The path of the file to write to. -- `text`: The text to write to the file. -- `permissions`: The permissions to set on the file if it is created (default is `0o644`). - -**Returns:** -Nothing. - -**Example:** -```tomo -(./file.txt).write("Hello, world!") -``` - ---- - -### `write_bytes` -Writes the given bytes to the file at the specified path, creating the file if -it doesn't already exist. Sets the file permissions as specified. If the file -writing cannot be successfully completed, a runtime error is raised. - -```tomo -func write(path: Path, bytes: [Byte], permissions=0o644[32] -> Void) -``` - -- `path`: The path of the file to write to. -- `bytes`: A list of bytes to write to the file. -- `permissions`: The permissions to set on the file if it is created (default is `0o644`). - -**Returns:** -Nothing. - -**Example:** -```tomo -(./file.txt).write_bytes([104[B], 105[B]]) -``` - ---- - -### `write_unique` -Writes the given text to a unique file path based on the specified path. The -file is created if it doesn't exist. This is useful for creating temporary -files. - -```tomo -func write_unique(path: Path, text: Text -> Path) -``` - -- `path`: The base path for generating the unique file. This path must include - the string `XXXXXX` in the file base name. -- `text`: The text to write to the file. - -**Returns:** -The path of the newly created unique file. - -**Example:** -```tomo ->> created := (./file-XXXXXX.txt).write_unique("Hello, world!") -= (./file-27QHtq.txt) ->> created.read() -= "Hello, world!" -created.remove() -``` - ---- - -### `write_unique_bytes` -Writes the given bytes to a unique file path based on the specified path. The -file is created if it doesn't exist. This is useful for creating temporary -files. - -```tomo -func write_unique_bytes(path: Path, bytes: [Byte] -> Path) -``` - -- `path`: The base path for generating the unique file. This path must include - the string `XXXXXX` in the file base name. -- `bytes`: The bytes to write to the file. - -**Returns:** -The path of the newly created unique file. - -**Example:** -```tomo ->> created := (./file-XXXXXX.txt).write_unique_bytes([1[B], 2[B], 3[B]]) -= (./file-27QHtq.txt) ->> created.read() -= [1[B], 2[B], 3[B]] -created.remove() -``` +[API documentation](../api/paths.md) diff --git a/docs/sets.md b/docs/sets.md index d40b825c..c8d67fc4 100644 --- a/docs/sets.md +++ b/docs/sets.md @@ -73,238 +73,6 @@ Set iteration operates over the value of the set when the loop began, so modifying the set during iteration is safe and will not result in the loop iterating over any of the new values. -## Set Methods +# API -- [`func add(set:|T|, item: T -> Void)`](#add) -- [`func add_all(set:@|T|, items: [T] -> Void)`](#add_all) -- [`func clear(set:@|T| -> Void)`](#clear) -- [`func has(set:|T|, item:T -> Bool)`](#has) -- [`func (set: |T|, other: |T|, strict: Bool = no -> Bool)`](#is_subset_of) -- [`func is_superset_of(set:|T|, other: |T|, strict: Bool = no -> Bool)`](#is_superset_of) -- [`func overlap(set:|T|, other: |T| -> |T|)`](#overlap) -- [`func remove(set:@|T|, item: T -> Void)`](#remove) -- [`func remove_all(set:@|T|, items: [T] -> Void)`](#remove_all) -- [`func with(set:|T|, other: |T| -> |T|)`](#with) -- [`func without(set:|T|, other: |T| -> |T|)`](#without) - -### `add` -Adds an item to the set. - -```tomo -func add(set:|T|, item: T -> Void) -``` - -- `set`: The mutable reference to the set. -- `item`: The item to add to the set. - -**Returns:** -Nothing. - -**Example:** -```tomo ->> nums.add(42) -``` - ---- - -### `add_all` -Adds multiple items to the set. - -```tomo -func add_all(set:@|T|, items: [T] -> Void) -``` - -- `set`: The mutable reference to the set. -- `items`: The list of items to add to the set. - -**Returns:** -Nothing. - -**Example:** -```tomo ->> nums.add_all([1, 2, 3]) -``` - ---- - -### `clear` -Removes all items from the set. - -```tomo -func clear(set:@|T| -> Void) -``` - -- `set`: The mutable reference to the set. - -**Returns:** -Nothing. - -**Example:** -```tomo ->> nums.clear() -``` - ---- - -### `has` -Checks if the set contains a specified item. - -```tomo -func has(set:|T|, item:T -> Bool) -``` - -- `set`: The set to check. -- `item`: The item to check for presence. - -**Returns:** -`yes` if the item is present, `no` otherwise. - -**Example:** -```tomo ->> |10, 20|.has(20) -= yes -``` - ---- - -### `is_subset_of` -Checks if the set is a subset of another set. - -```tomo -func (set: |T|, other: |T|, strict: Bool = no -> Bool) -``` - -- `set`: The set to check. -- `other`: The set to compare against. -- `strict`: If `yes`, checks if the set is a strict subset (does not equal the other set). - -**Returns:** -`yes` if the set is a subset of the other set (strictly or not), `no` otherwise. - -**Example:** -```tomo ->> |1, 2|.is_subset_of(|1, 2, 3|) -= yes -``` - ---- - -### `is_superset_of` -Checks if the set is a superset of another set. - -```tomo -func is_superset_of(set:|T|, other: |T|, strict: Bool = no -> Bool) -``` - -- `set`: The set to check. -- `other`: The set to compare against. -- `strict`: If `yes`, checks if the set is a strict superset (does not equal the other set). - -**Returns:** -`yes` if the set is a superset of the other set (strictly or not), `no` otherwise. - -**Example:** -```tomo ->> |1, 2, 3|.is_superset_of(|1, 2|) -= yes -``` -### `overlap` -Creates a new set with items that are in both the original set and another set. - -```tomo -func overlap(set:|T|, other: |T| -> |T|) -``` - -- `set`: The original set. -- `other`: The set to intersect with. - -**Returns:** -A new set containing only items present in both sets. - -**Example:** -```tomo ->> |1, 2|.overlap(|2, 3|) -= |2| -``` - ---- - -### `remove` -Removes an item from the set. - -```tomo -func remove(set:@|T|, item: T -> Void) -``` - -- `set`: The mutable reference to the set. -- `item`: The item to remove from the set. - -**Returns:** -Nothing. - -**Example:** -```tomo ->> nums.remove(42) -``` - ---- - -### `remove_all` -Removes multiple items from the set. - -```tomo -func remove_all(set:@|T|, items: [T] -> Void) -``` - -- `set`: The mutable reference to the set. -- `items`: The list of items to remove from the set. - -**Returns:** -Nothing. - -**Example:** -```tomo ->> nums.remove_all([1, 2, 3]) -``` - ---- - -### `with` -Creates a new set that is the union of the original set and another set. - -```tomo -func with(set:|T|, other: |T| -> |T|) -``` - -- `set`: The original set. -- `other`: The set to union with. - -**Returns:** -A new set containing all items from both sets. - -**Example:** -```tomo ->> |1, 2|.with(|2, 3|) -= |1, 2, 3| -``` - ---- - -### `without` -Creates a new set with items from the original set but without items from another set. - -```tomo -func without(set:|T|, other: |T| -> |T|) -``` - -- `set`: The original set. -- `other`: The set of items to remove from the original set. - -**Returns:** -A new set containing items from the original set excluding those in the other set. - -**Example:** -```tomo ->> |1, 2|.without(|2, 3|) -= |1| -``` +[API documentation](../api/sets.md) diff --git a/docs/tables.md b/docs/tables.md index d83a678b..2f07436a 100644 --- a/docs/tables.md +++ b/docs/tables.md @@ -150,169 +150,6 @@ Table iteration operates over the value of the table when the loop began, so modifying the table during iteration is safe and will not result in the loop iterating over any of the new values. -## Table Methods +# API -- [`func clear(t:&{K=V})`](#clear) -- [`func get(t:{K=V}, key: K -> V?)`](#get) -- [`func get_or_set(t:&{K=V}, key: K, default: V -> V)`](#get_or_set) -- [`func has(t:{K=V}, key: K -> Bool)`](#has) -- [`func remove(t:{K=V}, key: K -> Void)`](#remove) -- [`func set(t:{K=V}, key: K, value: V -> Void)`](#set) - ---- - -### `clear` -Removes all key-value pairs from the table. - -```tomo -func clear(t:&{K=V}) -``` - -- `t`: The reference to the table. - -**Returns:** -Nothing. - -**Example:** -```tomo ->> t.clear() -``` - ---- - -### `get` -Retrieves the value associated with a key, or returns `none` if the key is not present. -**Note:** default values for the table are ignored. - -```tomo -func get(t:{K=V}, key: K -> V?) -``` - -- `t`: The table. -- `key`: The key whose associated value is to be retrieved. - -**Returns:** -The value associated with the key or `none` if the key is not found. - -**Example:** -```tomo ->> t := {"A"=1, "B"=2} ->> t.get("A") -= 1? - ->> t.get("????") -= none - ->> t.get("A")! -= 1 - ->> t.get("????") or 0 -= 0 -``` - ---- - -### `get_or_set` -If the given key is in the table, return the associated value. Otherwise, -insert the given default value into the table and return it. - -**Note:** If no default value is provided explicitly, but the table has a -default value associated with it, the table's default value will be used. - -**Note:** The default value is only evaluated if the key is missing. - -```tomo -func get_or_set(t: &{K=V}, key: K, default: V -> V?) -``` - -- `t`: The table. -- `key`: The key whose associated value is to be retrieved. -- `default`: The default value to insert and return if the key is not present in the table. - -**Returns:** -Either the value associated with the key (if present) or the default value. The -table will be mutated if the key is not already present. - -**Example:** -```tomo ->> t := &{"A"=@[1, 2, 3]; default=@[]} ->> t.get_or_set("A").insert(4) ->> t.get_or_set("B").insert(99) ->> t -= &{"A"=@[1, 2, 3, 4], "B"=@[99]} - ->> t.get_or_set("C", @[0, 0, 0]) -= @[0, 0, 0] ->> t -= &{"A"=@[1, 2, 3, 4], "B"=@[99], "C"=@[0, 0, 0]} -``` - ---- - -### `has` -Checks if the table contains a specified key. - -```tomo -func has(t:{K=V}, key: K -> Bool) -``` - -- `t`: The table. -- `key`: The key to check for presence. - -**Returns:** -`yes` if the key is present, `no` otherwise. - -**Example:** -```tomo ->> {"A"=1, "B"=2}.has("A") -= yes ->> {"A"=1, "B"=2}.has("xxx") -= no -``` - ---- - -### `remove` -Removes the key-value pair associated with a specified key. - -```tomo -func remove(t:{K=V}, key: K -> Void) -``` - -- `t`: The reference to the table. -- `key`: The key of the key-value pair to remove. - -**Returns:** -Nothing. - -**Example:** -```tomo -t := {"A"=1, "B"=2} -t.remove("A") ->> t -= {"B"=2} -``` - ---- - -### `set` -Sets or updates the value associated with a specified key. - -```tomo -func set(t:{K=V}, key: K, value: V -> Void) -``` - -- `t`: The reference to the table. -- `key`: The key to set or update. -- `value`: The value to associate with the key. - -**Returns:** -Nothing. - -**Example:** -```tomo -t := {"A"=1, "B"=2} -t.set("C", 3) ->> t -= {"A"=1, "B"=2, "C"=3} -``` +[API documentation](../api/tables.md) diff --git a/docs/text.md b/docs/text.md index 35196d25..45ee9a09 100644 --- a/docs/text.md +++ b/docs/text.md @@ -145,7 +145,7 @@ These text literals can be used as interpolation values with or without parentheses, depending on which you find more readable: ``` -two_lines := "one$(\n)two" +two_lines := "one\ntwo" has_quotes := "some $\"quotes$\" here" ``` @@ -262,976 +262,6 @@ created that has text with the codepoint `U+E9` as a key, then a lookup with the same text but with `U+65 U+301` instead of `U+E9` will still succeed in finding the value because the two texts are equivalent under normalization. -## Text Functions +# API -- [`func as_c_string(text: Text -> CString)`](#as_c_string) -- [`func at(text: Text, index: Int -> Text)`](#at) -- [`func by_line(text: Text -> func(->Text?))`](#by_line) -- [`func by_split(text: Text, delimiter: Text = "" -> func(->Text?))`](#by_split) -- [`func by_split_any(text: Text, delimiters: Text = " $\t\r\n" -> func(->Text?))`](#by_split_any) -- [`func bytes(text: Text -> [Byte])`](#bytes) -- [`func caseless_equals(a: Text, b:Text, language:Text = "C" -> Bool)`](#caseless_equals) -- [`func codepoint_names(text: Text -> [Text])`](#codepoint_names) -- [`func ends_with(text: Text, suffix: Text -> Bool)`](#ends_with) -- [`func from(text: Text, first: Int -> Text)`](#from) -- [`func from_bytes(codepoints: [Int32] -> [Text])`](#from_bytes) -- [`func from_c_string(str: CString -> Text)`](#from_c_string) -- [`func from_codepoint_names(codepoint_names: [Text] -> [Text])`](#from_codepoint_names) -- [`func from_codepoints(codepoints: [Int32] -> [Text])`](#from_codepoints) -- [`func has(text: Text, target: Text -> Bool)`](#has) -- [`func join(glue: Text, pieces: [Text] -> Text)`](#join) -- [`func split(text: Text, delimiter: Text = "" -> [Text])`](#split) -- [`func split_any(text: Text, delimiters: Text = " $\t\r\n" -> [Text])`](#split_any) -- [`func middle_pad(text: Text, width: Int, pad: Text = " ", language: Text = "C" -> Text)`](#middle_pad) -- [`func left_pad(text: Text, width: Int, pad: Text = " ", language: Text = "C" -> Text)`](#left_pad) -- [`func lines(text: Text -> [Text])`](#lines) -- [`func lower(text: Text, language: Text = "C" -> Text)`](#lower) -- [`func quoted(text: Text, color: Bool = no, quotation_mark: Text = '"' -> Text)`](#quoted) -- [`func repeat(text: Text, count:Int -> Text)`](#repeat) -- [`func replace(text: Text, target: Text, replacement: Text -> Text)`](#replace) -- [`func reversed(text: Text -> Text)`](#reversed) -- [`func right_pad(text: Text, width: Int, pad: Text = " ", language: Text = "C" -> Text)`](#right_pad) -- [`func slice(text: Text, from: Int = 1, to: Int = -1 -> Text)`](#slice) -- [`func starts_with(text: Text, prefix: Text -> Bool)`](#starts_with) -- [`func title(text: Text, language: Text = "C" -> Text)`](#title) -- [`func to(text: Text, last: Int -> Text)`](#to) -- [`func translate(translations:{Text=Text} -> Text)`](#translate) -- [`func trim(text: Text, to_trim: Text = " $\t\r\n", left: Bool = yes, right: Bool = yes -> Text)`](#trim) -- [`func upper(text: Text, language: Text "C" -> Text)`](#upper) -- [`func utf32_codepoints(text: Text -> [Int32])`](#utf32_codepoints) -- [`func width(text: Text -> Int)`](#width) -- [`func without_prefix(text: Text, prefix: Text -> Text)`](#without_prefix) -- [`func without_suffix(text: Text, suffix: Text -> Text)`](#without_suffix) - ----------------- - -### `as_c_string` -Converts a `Text` value to a C-style string. - -```tomo -func as_c_string(text: Text -> CString) -``` - -- `text`: The text to be converted to a C-style string. - -**Returns:** -A C-style string (`CString`) representing the text. - -**Example:** -```tomo ->> "Hello".as_c_string() -= CString("Hello") -``` - ---- - -### `at` -Get the graphical cluster at a given index. This is similar to `str[i]` with -ASCII text, but has more correct behavior for unicode text. - -```tomo -func at(text: Text, index: Int -> Text) -``` - -- `text`: The text from which to get a cluster. -- `index`: The index of the graphical cluster (1-indexed). - -**Returns:** -A `Text` with the single graphical cluster at the given index. Note: negative -indices are counted from the back of the text, so `-1` means the last cluster, -`-2` means the second-to-last, and so on. - -**Example:** -```tomo ->> "Amélie".at(3) -= "é" -``` - ---- - -### `by_line` -Returns an iterator function that can be used to iterate over the lines in a -text. - -```tomo -func by_line(text: Text -> func(->Text?)) -``` - -- `text`: The text to be iterated over, line by line. - -**Returns:** -An iterator function that returns one line at a time, until it runs out and -returns `none`. **Note:** this function ignores a trailing newline if there is -one. If you don't want this behavior, use `text.by_split($/{1 nl}/)` instead. - -**Example:** -```tomo -text := " - line one - line two -" -for line in text.by_line() - # Prints: "line one" then "line two": - say(line) -``` - ---- - -### `by_split` -Returns an iterator function that can be used to iterate over text separated by -a delimiter. -**Note:** to split based on a set of delimiters, use [`by_split_any()`](#by_split_any). - -```tomo -func by_split(text: Text, delimiter: Text = "" -> func(->Text?)) -``` - -- `text`: The text to be iterated over in delimited chunks. -- `delimiter`: An exact delimiter to use for splitting the text. If an empty text - is given, then each split will be the graphical clusters of the text. - -**Returns:** -An iterator function that returns one chunk of text at a time, separated by the -given delimiter, until it runs out and returns `none`. **Note:** using an empty -delimiter (the default) will iterate over single grapheme clusters in the text. - -**Example:** -```tomo -text := "one,two,three" -for chunk in text.by_split(",") - # Prints: "one" then "two" then "three": - say(chunk) -``` - ---- - -### `by_split_any` -Returns an iterator function that can be used to iterate over text separated by -one or more characters (grapheme clusters) from a given text of delimiters. -**Note:** to split based on an exact delimiter, use [`by_split()`](#by_split). - -```tomo -func by_split_any(text: Text, delimiters: Text = " $\t\r\n" -> func(->Text?)) -``` - -- `text`: The text to be iterated over in delimited chunks. -- `delimiters`: An text containing multiple delimiter characters (grapheme clusters) - to use for splitting the text. - -**Returns:** -An iterator function that returns one chunk of text at a time, separated by the -given delimiter characters, until it runs out and returns `none`. - -**Example:** -```tomo -text := "one,two,;,three" -for chunk in text.by_split_any(",;") - # Prints: "one" then "two" then "three": - say(chunk) -``` - ---- - -### `bytes` -Converts a `Text` value to a list of bytes representing a UTF8 encoding of -the text. - -```tomo -func bytes(text: Text -> [Byte]) -``` - -- `text`: The text to be converted to UTF8 bytes. - -**Returns:** -A list of bytes (`[Byte]`) representing the text in UTF8 encoding. - -**Example:** -```tomo ->> "Amélie".bytes() -= [65[B], 109[B], 195[B], 169[B], 108[B], 105[B], 101[B]] : [Byte] -``` - ---- - -### `caseless_equals` -Checks whether two texts are equal, ignoring the casing of the letters (i.e. -case-insensitive comparison). - -```tomo -func caseless_equals(a: Text, b:Text, language:Text = "C" -> Bool) -``` - -- `a`: The first text to compare case-insensitively. -- `b`: The second text to compare case-insensitively. -- `language`: The ISO 639 language code for which casing rules to use. - -**Returns:** -`yes` if `a` and `b` are equal to each other, ignoring casing, otherwise `no`. - -**Example:** -```tomo ->> "A".caseless_equals("a") -= yes - -# Turkish lowercase "I" is "ı" (dotless I), not "i" ->> "I".caseless_equals("i", language="tr_TR") -= no -``` - ---- - -### `codepoint_names` -Returns a list of the names of each codepoint in the text. - -```tomo -func codepoint_names(text: Text -> [Text]) -``` - -- `text`: The text from which to extract codepoint names. - -**Returns:** -A list of codepoint names (`[Text]`). - -**Example:** -```tomo ->> "Amélie".codepoint_names() -= ["LATIN CAPITAL LETTER A", "LATIN SMALL LETTER M", "LATIN SMALL LETTER E WITH ACUTE", "LATIN SMALL LETTER L", "LATIN SMALL LETTER I", "LATIN SMALL LETTER E"] -``` - ---- - -### `ends_with` -Checks if the `Text` ends with a literal suffix text. - -```tomo -func ends_with(text: Text, suffix: Text -> Bool) -``` - -- `text`: The text to be searched. -- `suffix`: The literal suffix text to check for. - -**Returns:** -`yes` if the text has the target, `no` otherwise. - -**Example:** -```tomo ->> "hello world".ends_with("world") -= yes -``` - ---- - -### `from` -Get a slice of the text, starting at the given position. - -```tomo -func from(text: Text, first: Int -> Text) -``` - -- `text`: The text to be sliced. -- `frist`: The index of the first grapheme cluster to include (1-indexed). - -**Returns:** -The text from the given grapheme cluster to the end of the text. Note: a -negative index counts backwards from the end of the text, so `-1` refers to the -last cluster, `-2` the second-to-last, etc. Slice ranges will be truncated to -the length of the text. - -**Example:** -```tomo ->> "hello".from(2) -= "ello" - ->> "hello".from(-2) -= "lo" -``` - ---- - -### `from_bytes` -Returns text that has been constructed from the given UTF8 bytes. Note: the -text will be normalized, so the resulting text's UTF8 bytes may not exactly -match the input. - -```tomo -func from_bytes(bytes: [Byte] -> [Text]) -``` - -- `bytes`: The UTF-8 bytes of the desired text. - -**Returns:** -A new text based on the input UTF8 bytes after normalization has been applied. - -**Example:** -```tomo ->> Text.from_bytes([195[B], 133[B], 107[B], 101[B]]) -= "Åke" -``` - ---- - -### `from_c_string` -Converts a C-style string to a `Text` value. - -```tomo -func from_c_string(str: CString -> Text) -``` - -- `str`: The C-style string to be converted. - -**Returns:** -A `Text` value representing the C-style string. - -**Example:** -```tomo ->> Text.from_c_string(CString("Hello")) -= "Hello" -``` - ---- - -### `from_codepoint_names` -Returns text that has the given codepoint names (according to the Unicode -specification) as its codepoints. Note: the text will be normalized, so the -resulting text's codepoints may not exactly match the input codepoints. - -```tomo -func from_codepoint_names(codepoint_names: [Text] -> [Text]) -``` - -- `codepoint_names`: The names of each codepoint in the desired text. Names - are case-insentive. - -**Returns:** -A new text with the specified codepoints after normalization has been applied. -Any invalid names are ignored. - -**Example:** -```tomo ->> Text.from_codepoint_names([ - "LATIN CAPITAL LETTER A WITH RING ABOVE", - "LATIN SMALL LETTER K", - "LATIN SMALL LETTER E", -] -= "Åke" -``` - ---- - -### `from_codepoints` -Returns text that has been constructed from the given UTF32 codepoints. Note: -the text will be normalized, so the resulting text's codepoints may not exactly -match the input codepoints. - -```tomo -func from_codepoints(codepoints: [Int32] -> [Text]) -``` - -- `codepoints`: The UTF32 codepoints in the desired text. - -**Returns:** -A new text with the specified codepoints after normalization has been applied. - -**Example:** -```tomo ->> Text.from_codepoints([197[32], 107[32], 101[32]]) -= "Åke" -``` - ---- - -### `has` -Checks if the `Text` contains some target text. - -```tomo -func has(text: Text, target: Text -> Bool) -``` - -- `text`: The text to be searched. -- `target`: The text to search for. - -**Returns:** -`yes` if the target text is found, `no` otherwise. - -**Example:** -```tomo ->> "hello world".has("wo") -= yes ->> "hello world".has("xxx") -= no -``` - ---- - -### `join` -Joins a list of text pieces with a specified glue. - -```tomo -func join(glue: Text, pieces: [Text] -> Text) -``` - -- `glue`: The text used to join the pieces. -- `pieces`: The list of text pieces to be joined. - -**Returns:** -A single `Text` value with the pieces joined by the glue. - -**Example:** -```tomo ->> ", ".join(["one", "two", "three"]) -= "one, two, three" -``` - ---- - -### `middle_pad` -Pad some text on the left and right side so it reaches a target width. - -```tomo -func middle_pad(text: Text, width: Int, pad: Text = " ", language: Text = "C" -> Text) -``` - -- `text`: The text to pad. -- `width`: The target width. -- `pad`: The padding text (default: `" "`). -- `language`: The ISO 639 language code for which character width to use. - -**Returns:** -Text with length at least `width`, with extra padding on the left and right as -needed. If `pad` has length greater than 1, it may be partially repeated to -reach the exact desired length. - -**Example:** -```tomo ->> "x".middle_pad(6) -= " x " ->> "x".middle_pad(10, "ABC") -= "ABCAxABCAB" -``` - ---- - -### `left_pad` -Pad some text on the left side so it reaches a target width. - -```tomo -func left_pad(text: Text, width: Int, pad: Text = " ", language: Text = "C" -> Text) -``` - -- `text`: The text to pad. -- `width`: The target width. -- `pad`: The padding text (default: `" "`). -- `language`: The ISO 639 language code for which character width to use. - -**Returns:** -Text with length at least `width`, with extra padding on the left as needed. If -`pad` has length greater than 1, it may be partially repeated to reach the -exact desired length. - -**Example:** -```tomo ->> "x".left_pad(5) -= " x" ->> "x".left_pad(5, "ABC") -= "ABCAx" -``` - ---- - -### `lines` -Splits the text into a list of lines of text, preserving blank lines, -ignoring trailing newlines, and handling `\r\n` the same as `\n`. - -```tomo -func lines(text: Text -> [Text]) -``` - -- `text`: The text to be split into lines. - -**Returns:** -A list of substrings resulting from the split. - -**Example:** -```tomo ->> "one$(\n)two$(\n)three".lines() -= ["one", "two", "three"] ->> "one$(\n)two$(\n)three$(\n)".lines() -= ["one", "two", "three"] ->> "one$(\n)two$(\n)three$(\n\n)".lines() -= ["one", "two", "three", ""] ->> "one$(\r\n)two$(\r\n)three$(\r\n)".lines() -= ["one", "two", "three"] ->> "".lines() -= [] -``` - ---- - -### `lower` -Converts all characters in the text to lowercase. - -```tomo -func lower(text: Text, language: Text = "C" -> Text) -``` - -- `text`: The text to be converted to lowercase. -- `language`: The ISO 639 language code for which casing rules to use. - -**Returns:** -The lowercase version of the text. - -**Example:** -```tomo ->> "AMÉLIE".lower() -= "amélie" - ->> "I".lower(language="tr_TR") ->> "ı" -``` - ---- - -### `quoted` -Formats the text with quotation marks and escapes. - -```tomo -func quoted(text: Text, color: Bool = no, quotation_mark: Text = '"' -> Text) -``` - -- `text`: The text to be quoted. -- `color`: Whether to add color formatting (default is `no`). -- `quotation_mark`: The quotation mark to use (default is `"`). - -**Returns:** -The text formatted as a quoted text. - -**Example:** -```tomo ->> "one$(\n)two".quoted() -= "\"one\\ntwo\"" -``` - ---- - -### `repeat` -Repeat some text multiple times. - -```tomo -func repeat(text: Text, count:Int -> Text) -``` - -- `text`: The text to repeat. -- `count`: The number of times to repeat it. (Negative numbers are equivalent to zero). - -**Returns:** -The text repeated the given number of times. - -**Example:** -```tomo ->> "Abc".repeat(3) -= "AbcAbcAbc" -``` - ---- - -### `replace` -Replaces occurrences of a target text with a replacement text. - -```tomo -func replace(text: Text, target: Text, replacement: Text -> Text) -``` - -- `text`: The text in which to perform replacements. -- `target`: The target text to be replaced. -- `replacement`: The text to replace the target with. - -**Returns:** -The text with occurrences of the target replaced. - -**Example:** -```tomo ->> "Hello world".replace("world", "there") -= "Hello there" -``` - ---- - -### `reversed` -Return a text that has the grapheme clusters in reverse order. - -```tomo -func reversed(text: Text -> Text) -``` - -- `text`: The text to reverse. - -**Returns:** -A reversed version of the text. - -**Example:** -```tomo ->> "Abc".reversed() -= "cbA" -``` - ---- - -### `right_pad` -Pad some text on the right side so it reaches a target width. - -```tomo -func right_pad(text: Text, width: Int, pad: Text = " ", language: Text = "C" -> Text) -``` - -- `text`: The text to pad. -- `width`: The target width. -- `pad`: The padding text (default: `" "`). -- `language`: The ISO 639 language code for which character width to use. - -**Returns:** -Text with length at least `width`, with extra padding on the right as needed. If -`pad` has length greater than 1, it may be partially repeated to reach the -exact desired length. - -**Example:** -```tomo ->> "x".right_pad(5) -= "x " ->> "x".right_pad(5, "ABC") -= "xABCA" -``` - ---- - -### `slice` -Get a slice of the text. - -```tomo -func slice(text: Text, from: Int = 1, to: Int = -1 -> Text) -``` - -- `text`: The text to be sliced. -- `from`: The index of the first grapheme cluster to include (1-indexed). -- `to`: The index of the last grapheme cluster to include (1-indexed). - -**Returns:** -The text that spans the given grapheme cluster indices. Note: a negative index -counts backwards from the end of the text, so `-1` refers to the last cluster, -`-2` the second-to-last, etc. Slice ranges will be truncated to the length of -the text. - -**Example:** -```tomo ->> "hello".slice(2, 3) -= "el" - ->> "hello".slice(to=-2) -= "hell" - ->> "hello".slice(from=2) -= "ello" -``` - ---- - -### `split` -Splits the text into a list of substrings based on exact matches of a delimiter. -**Note:** to split based on a set of delimiter characters, use [`split_any()`](#split_any). - -```tomo -func split(text: Text, delimiter: Text = "" -> [Text]) -``` - -- `text`: The text to be split. -- `delimiter`: The delimiter used to split the text. If the delimiter is the - empty text, the text will be split into individual grapheme clusters. - -**Returns:** -A list of subtexts resulting from the split. - -**Example:** -```tomo ->> "one,two,,three".split(",") -= ["one", "two", "", "three"] - ->> "abc".split() -= ["a", "b", "c"] -``` - ---- - -### `split_any` -Splits the text into a list of substrings at one or more occurrences of a set -of delimiter characters (grapheme clusters). -**Note:** to split based on an exact delimiter, use [`split()`](#split). - -```tomo -func split_any(text: Text, delimiters: Text = " $\t\r\n" -> [Text]) -``` - -- `text`: The text to be split. -- `delimiters`: A text containing multiple delimiters to be used for - splitting the text into chunks. - -**Returns:** -A list of subtexts resulting from the split. - -**Example:** -```tomo ->> "one, two,,three".split_any(", ") -= ["one", "two", "three"] -``` - ---- - -### `starts_with` -Checks if the `Text` starts with a literal prefix text. - -```tomo -func starts_with(text: Text, prefix: Text -> Bool) -``` - -- `text`: The text to be searched. -- `prefix`: The literal prefix text to check for. - -**Returns:** -`yes` if the text has the given prefix, `no` otherwise. - -**Example:** -```tomo ->> "hello world".starts_with("hello") -= yes -``` - ---- - -### `title` -Converts the text to title case (capitalizing the first letter of each word). - -```tomo -func title(text: Text, language: Text = "C" -> Text) -``` - -- `text`: The text to be converted to title case. -- `language`: The ISO 639 language code for which casing rules to use. - -**Returns:** -The text in title case. - -**Example:** -```tomo ->> "amélie".title() -= "Amélie" - -# In Turkish, uppercase "i" is "İ" ->> "i".title(language="tr_TR") -= "İ" -``` - ---- - -### `to` -Get a slice of the text, ending at the given position. - -```tomo -func to(text: Text, last: Int -> Text) -``` - -- `text`: The text to be sliced. -- `last`: The index of the last grapheme cluster to include (1-indexed). - -**Returns:** -The text up to and including the given grapheme cluster. Note: a negative index -counts backwards from the end of the text, so `-1` refers to the last cluster, -`-2` the second-to-last, etc. Slice ranges will be truncated to the length of -the text. - -**Example:** -```tomo ->> "goodbye".to(3) -= "goo" - ->> "goodbye".to(-2) -= "goodby" -``` - ---- - -### `translate` -Takes a table mapping target texts to their replacements and performs all the -replacements in the table on the whole text. At each position, the first -matching replacement is applied and the matching moves on to *after* the -replacement text, so replacement text is not recursively modified. See -[`replace()`](#replace) for more information about replacement behavior. - -```tomo -func translate(translations:{Text=Text} -> Text) -``` - -- `text`: The text in which to perform replacements. -- `translations`: A table mapping from target text to its replacement. - -**Returns:** -The text with all occurrences of the targets replaced with their corresponding -replacement text. - -**Example:** -```tomo ->> "A & an amperand".translate({ - "&" = "&", - "<" = "<", - ">" = ">", - '"" = """, - "'" = "'", -} -= "A <tag> & an ampersand" -``` - ---- - -### `trim` -Trims the given characters (grapheme clusters) from the left and/or right side of the text. - -```tomo -func trim(text: Text, to_trim: Text = " $\t\r\n", left: Bool = yes, right: Bool = yes -> Text) -``` - -- `text`: The text to be trimmed. -- `to_trim`: The characters to remove from the left/right of the text. -- `left`: Whether or not to trim from the front of the text. -- `right`: Whether or not to trim from the back of the text. - -**Returns:** -The text without the trim characters at either end. - -**Example:** -```tomo ->> " x y z $(\n)".trim() -= "x y z" - ->> "one,".trim(",") -= "one" - ->> " xyz ".trim(right=no) -= "xyz " -``` - ---- - -### `upper` -Converts all characters in the text to uppercase. - -```tomo -func upper(text: Text, language: Text = "C" -> Text) -``` - -- `text`: The text to be converted to uppercase. -- `language`: The ISO 639 language code for which casing rules to use. - -**Returns:** -The uppercase version of the text. - -**Example:** -```tomo ->> "amélie".upper() -= "AMÉLIE" - -# In Turkish, uppercase "i" is "İ" ->> "i".upper(language="tr_TR") -= "İ" -``` - ---- - -### `utf32_codepoints` -Returns a list of Unicode code points for UTF32 encoding of the text. - -```tomo -func utf32_codepoints(text: Text -> [Int32]) -``` - -- `text`: The text from which to extract Unicode code points. - -**Returns:** -A list of 32-bit integer Unicode code points (`[Int32]`). - -**Example:** -```tomo ->> "Amélie".utf32_codepoints() -= [65[32], 109[32], 233[32], 108[32], 105[32], 101[32]] : [Int32] -``` - ---- - -### `width` -Returns the display width of the text as seen in a terminal with appropriate -font rendering. This is usually the same as the text's `.length`, but there are -some characters like emojis that render wider than 1 cell. - -**Warning:** This will not always be exactly accurate when your terminal's font -rendering can't handle some unicode displaying correctly. - -```tomo -func width(text: Text -> Int) -``` - -- `text`: The text whose length you want. - -**Returns:** -An integer representing the display width of the text. - -**Example:** -```tomo ->> "Amélie".width() -= 6 ->> "🤠".width() -= 2 -``` - ---- - -### `without_prefix` -Returns the text with a given prefix removed (if present). - -```tomo -func without_prefix(text: Text, prefix: Text -> Text) -``` - -- `text`: The text to remove the prefix from. -- `prefix`: The prefix to remove. - -**Returns:** -A text without the given prefix (if present) or the unmodified text if the -prefix is not present. - -**Example:** -```tomo ->> "foo:baz".without_prefix("foo:") -= "baz" ->> "qux".without_prefix("foo:") -= "qux" -``` - ---- - -### `without_suffix` -Returns the text with a given suffix removed (if present). - -```tomo -func without_suffix(text: Text, suffix: Text -> Text) -``` - -- `text`: The text to remove the suffix from. -- `suffix`: The suffix to remove. - -**Returns:** -A text without the given suffix (if present) or the unmodified text if the -suffix is not present. - -**Example:** -```tomo ->> "baz.foo".without_suffix(".foo") -= "baz" ->> "qux".without_suffix(".foo") -= "qux" -``` +[API documentation](../api/text.md) diff --git a/docs/tomo.1 b/docs/tomo.1 deleted file mode 100644 index bbc90f8e..00000000 --- a/docs/tomo.1 +++ /dev/null @@ -1,75 +0,0 @@ -.\" Automatically generated by Pandoc 3.1.12.1 -.\" -.TH "TOMO" "1" "June 11, 2024" "" "" -.SH NAME -tomo \- The programming language of tomorrow. -.SH SYNOPSIS -.TP -Run the REPL: -\f[B]tomo\f[R] -.TP -Run a program: -\f[B]tomo\f[R] \f[I]program.tm\f[R] [[\f[B]\-\-\f[R]] -\f[I]args\&...\f[R]] -.TP -Transpile tomo files to C files: -\f[B]tomo\f[R] \f[B]\-t\f[R] \f[I]file1.tm\f[R] \f[I]file2.tm\f[R]\&... -.TP -Compile files to static object files: -\f[B]tomo\f[R] \f[B]\-c\f[R] \f[I]file1.tm\f[R] \f[I]file2.tm\f[R]\&... -.TP -Compile file to an executable: -\f[B]tomo\f[R] \f[B]\-e\f[R] \f[I]file1.tm\f[R] -.TP -Build a shared library: -\f[B]tomo\f[R] \f[B]\-s=\f[R]\f[I]mylib.1.2.3\f[R] \f[I]file1.tm\f[R] -\f[I]file2.tm\f[R]\&... -.SH DESCRIPTION -Tomo is a programming language that is statically typed, compiled, -small, and garbage\-collected, with concise syntax and built\-in support -for high\-performance, low\-overhead datastructures. -It compiles by first outputting C code, which is then compiled using a C -compiler of your choice. -.SH OPTIONS -.TP -\f[B]\-h\f[R], \f[B]\-\-help\f[R] -Print the usage and exit. -.TP -\f[B]\-t\f[R], \f[B]\-\-transpile\f[R] -Transpile the input files to C code without compiling them. -.TP -\f[B]\-c\f[R], \f[B]\-\-compile\-obj\f[R] -Compile the input files to static objects, rather than running them. -.TP -\f[B]\-e\f[R], \f[B]\-\-compile\-exe\f[R] -Compile the input file to an executable. -.TP -\f[B]\-L\f[R], \f[B]\-\-library\f[R] -Compile the input files to a shared library file and header. -.TP -\f[B]\-I\f[R], \f[B]\-\-install\f[R] -Install the compiled executable or library. -.TP -\f[B]\-C\f[R] \f[I]\f[R], \f[B]\-\-show\-codegen\f[R] \f[I]\f[R] -Set a program (e.g.\ \f[B]cat\f[R] or \f[B]bat\f[R]) to display the -generated code -.TP -\f[B]\-\-c\-compiler\f[R] -Set which C compiler is used. -.TP -\f[B]\-O\f[R] \f[B]level\f[R], \f[B]\-\-optimization\f[R] \f[B]level\f[R] -Set the optimization level. -.TP -\f[B]\-v\f[R], \f[B]\-\-verbose\f[R] -Print extra verbose output. -.TP -\f[B]\-r\f[R], \f[B]\-\-run\f[R] -Run an installed tomo program from -\f[B]\[ti]/.local/share/tomo/installed\f[R]. -.SS ENVIRONMENT VARIABLES -Some options can be configured by setting environment variables. -.TP -\f[B]CC=\f[R]\f[I]c\-compiler\f[R] -Set which C compiler is used. -.SH AUTHORS -Bruce Hill (\f[I]bruce\[at]bruce\-hill.com\f[R]). diff --git a/man/man1/tomo.1 b/man/man1/tomo.1 new file mode 100644 index 00000000..bbc90f8e --- /dev/null +++ b/man/man1/tomo.1 @@ -0,0 +1,75 @@ +.\" Automatically generated by Pandoc 3.1.12.1 +.\" +.TH "TOMO" "1" "June 11, 2024" "" "" +.SH NAME +tomo \- The programming language of tomorrow. +.SH SYNOPSIS +.TP +Run the REPL: +\f[B]tomo\f[R] +.TP +Run a program: +\f[B]tomo\f[R] \f[I]program.tm\f[R] [[\f[B]\-\-\f[R]] +\f[I]args\&...\f[R]] +.TP +Transpile tomo files to C files: +\f[B]tomo\f[R] \f[B]\-t\f[R] \f[I]file1.tm\f[R] \f[I]file2.tm\f[R]\&... +.TP +Compile files to static object files: +\f[B]tomo\f[R] \f[B]\-c\f[R] \f[I]file1.tm\f[R] \f[I]file2.tm\f[R]\&... +.TP +Compile file to an executable: +\f[B]tomo\f[R] \f[B]\-e\f[R] \f[I]file1.tm\f[R] +.TP +Build a shared library: +\f[B]tomo\f[R] \f[B]\-s=\f[R]\f[I]mylib.1.2.3\f[R] \f[I]file1.tm\f[R] +\f[I]file2.tm\f[R]\&... +.SH DESCRIPTION +Tomo is a programming language that is statically typed, compiled, +small, and garbage\-collected, with concise syntax and built\-in support +for high\-performance, low\-overhead datastructures. +It compiles by first outputting C code, which is then compiled using a C +compiler of your choice. +.SH OPTIONS +.TP +\f[B]\-h\f[R], \f[B]\-\-help\f[R] +Print the usage and exit. +.TP +\f[B]\-t\f[R], \f[B]\-\-transpile\f[R] +Transpile the input files to C code without compiling them. +.TP +\f[B]\-c\f[R], \f[B]\-\-compile\-obj\f[R] +Compile the input files to static objects, rather than running them. +.TP +\f[B]\-e\f[R], \f[B]\-\-compile\-exe\f[R] +Compile the input file to an executable. +.TP +\f[B]\-L\f[R], \f[B]\-\-library\f[R] +Compile the input files to a shared library file and header. +.TP +\f[B]\-I\f[R], \f[B]\-\-install\f[R] +Install the compiled executable or library. +.TP +\f[B]\-C\f[R] \f[I]\f[R], \f[B]\-\-show\-codegen\f[R] \f[I]\f[R] +Set a program (e.g.\ \f[B]cat\f[R] or \f[B]bat\f[R]) to display the +generated code +.TP +\f[B]\-\-c\-compiler\f[R] +Set which C compiler is used. +.TP +\f[B]\-O\f[R] \f[B]level\f[R], \f[B]\-\-optimization\f[R] \f[B]level\f[R] +Set the optimization level. +.TP +\f[B]\-v\f[R], \f[B]\-\-verbose\f[R] +Print extra verbose output. +.TP +\f[B]\-r\f[R], \f[B]\-\-run\f[R] +Run an installed tomo program from +\f[B]\[ti]/.local/share/tomo/installed\f[R]. +.SS ENVIRONMENT VARIABLES +Some options can be configured by setting environment variables. +.TP +\f[B]CC=\f[R]\f[I]c\-compiler\f[R] +Set which C compiler is used. +.SH AUTHORS +Bruce Hill (\f[I]bruce\[at]bruce\-hill.com\f[R]). diff --git a/man/man3/tomo-Bool.parse.3 b/man/man3/tomo-Bool.parse.3 new file mode 100644 index 00000000..6c722b99 --- /dev/null +++ b/man/man3/tomo-Bool.parse.3 @@ -0,0 +1,38 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Bool.parse 3 2025-04-19T14:30:40.359614 "Tomo man-pages" +.SH NAME +Bool.parse \- Converts a string representation of a boolean value into a boolean. Acceptable boolean values are case-insensitive variations of `yes`/`no`, `y`/`n`, `true`/`false`, `on`/`off`. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Bool.parse : func(text: Text -> Bool?)" +.fi + +.SH DESCRIPTION +Converts a string representation of a boolean value into a boolean. Acceptable boolean values are case-insensitive variations of `yes`/`no`, `y`/`n`, `true`/`false`, `on`/`off`. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The string containing the boolean value. - +.TE +.SH RETURN +`yes` if the string matches a recognized truthy boolean value; otherwise return `no`. + +.SH EXAMPLES +.EX +>> Bool.parse("yes") += yes : Bool? +>> Bool.parse("no") += no : Bool? +>> Bool.parse("???") += none : Bool? +.EE diff --git a/man/man3/tomo-Byte.hex.3 b/man/man3/tomo-Byte.hex.3 new file mode 100644 index 00000000..f55fde16 --- /dev/null +++ b/man/man3/tomo-Byte.hex.3 @@ -0,0 +1,36 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Byte.hex 3 2025-04-19T14:30:40.360114 "Tomo man-pages" +.SH NAME +Byte.hex \- Convert a byte to a hexidecimal text representation. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Byte.hex : func(byte: Byte, uppercase: Bool = yes, prefix: Bool = no -> Text)" +.fi + +.SH DESCRIPTION +Convert a byte to a hexidecimal text representation. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +byte Byte The byte to convert to hex. - +uppercase Bool Whether or not to use uppercase hexidecimal letters. yes +prefix Bool Whether or not to prepend a `0x` prefix. no +.TE +.SH RETURN +The byte as a hexidecimal text. + +.SH EXAMPLES +.EX +>> Byte(18).hex() += "0x12" +.EE diff --git a/man/man3/tomo-Byte.is_between.3 b/man/man3/tomo-Byte.is_between.3 new file mode 100644 index 00000000..c963d054 --- /dev/null +++ b/man/man3/tomo-Byte.is_between.3 @@ -0,0 +1,40 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Byte.is_between 3 2025-04-19T14:30:40.360176 "Tomo man-pages" +.SH NAME +Byte.is_between \- Determines if an integer is between two numbers (inclusive). + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Byte.is_between : func(x: Byte, low: Byte, high: Byte -> Bool)" +.fi + +.SH DESCRIPTION +Determines if an integer is between two numbers (inclusive). + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Byte The integer to be checked. - +low Byte The lower bound to check (inclusive). - +high Byte The upper bound to check (inclusive). - +.TE +.SH RETURN +`yes` if `low <= x and x <= high`, otherwise `no` + +.SH EXAMPLES +.EX +>> Byte(7).is_between(1, 10) += yes +>> Byte(7).is_between(100, 200) += no +>> Byte(7).is_between(1, 7) += yes +.EE diff --git a/man/man3/tomo-Byte.parse.3 b/man/man3/tomo-Byte.parse.3 new file mode 100644 index 00000000..76e35a3a --- /dev/null +++ b/man/man3/tomo-Byte.parse.3 @@ -0,0 +1,36 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Byte.parse 3 2025-04-19T14:30:40.360223 "Tomo man-pages" +.SH NAME +Byte.parse \- Parse a byte literal from text. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Byte.parse : func(text: Text -> Byte?)" +.fi + +.SH DESCRIPTION +Parse a byte literal from text. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to parse. - +.TE +.SH RETURN +The byte parsed from the text, if successful, otherwise `none`. + +.SH EXAMPLES +.EX +>> Byte.parse("5") += Byte(5)? +>> Byte.parse("asdf") += none +.EE diff --git a/man/man3/tomo-Byte.to.3 b/man/man3/tomo-Byte.to.3 new file mode 100644 index 00000000..149c2126 --- /dev/null +++ b/man/man3/tomo-Byte.to.3 @@ -0,0 +1,43 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Byte.to 3 2025-04-19T14:30:40.360261 "Tomo man-pages" +.SH NAME +Byte.to \- Returns an iterator function that iterates over the range of bytes specified. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Byte.to : func(first: Byte, last: Byte, step: Byte? = none -> func(->Byte?))" +.fi + +.SH DESCRIPTION +Returns an iterator function that iterates over the range of bytes specified. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +first Byte The starting value of the range. - +last Byte The ending value of the range. - +step Byte? An optional step size to use. If unspecified or `none`, the step will be inferred to be `+1` if `last >= first`, otherwise `-1`. none +.TE +.SH RETURN +An iterator function that returns each byte in the given range (inclusive). + +.SH EXAMPLES +.EX +>> Byte(2).to(5) += func(->Byte?) +>> [x for x in Byte(2).to(5)] += [Byte(2), Byte(3), Byte(4), Byte(5)] +>> [x for x in Byte(5).to(2)] += [Byte(5), Byte(4), Byte(3), Byte(2)] + +>> [x for x in Byte(2).to(5, step=2)] += [Byte(2), Byte(4)] +.EE diff --git a/man/man3/tomo-Int.abs.3 b/man/man3/tomo-Int.abs.3 new file mode 100644 index 00000000..7ef53d0b --- /dev/null +++ b/man/man3/tomo-Int.abs.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Int.abs 3 2025-04-19T14:30:40.360304 "Tomo man-pages" +.SH NAME +Int.abs \- Calculates the absolute value of an integer. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Int.abs : func(x: Int -> Int)" +.fi + +.SH DESCRIPTION +Calculates the absolute value of an integer. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Int The integer whose absolute value is to be calculated. - +.TE +.SH RETURN +The absolute value of `x`. + +.SH EXAMPLES +.EX +>> (-10).abs() += 10 +.EE diff --git a/man/man3/tomo-Int.choose.3 b/man/man3/tomo-Int.choose.3 new file mode 100644 index 00000000..aeb1d4b7 --- /dev/null +++ b/man/man3/tomo-Int.choose.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Int.choose 3 2025-04-19T14:30:40.360341 "Tomo man-pages" +.SH NAME +Int.choose \- Computes the binomial coefficient of the given numbers (the equivalent of `n` choose `k` in combinatorics). This is equal to `n.factorial()/(k.factorial() * (n-k).factorial())`. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Int.choose : func(n: Int, k: Int -> Int)" +.fi + +.SH DESCRIPTION +Computes the binomial coefficient of the given numbers (the equivalent of `n` choose `k` in combinatorics). This is equal to `n.factorial()/(k.factorial() * (n-k).factorial())`. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +n Int The number of things to choose from. - +k Int The number of things to be chosen. - +.TE +.SH RETURN +The binomial coefficient, equivalent to the number of ways to uniquely choose `k` objects from among `n` objects, ignoring order. + +.SH EXAMPLES +.EX +>> (4).choose(2) += 6 +.EE diff --git a/man/man3/tomo-Int.clamped.3 b/man/man3/tomo-Int.clamped.3 new file mode 100644 index 00000000..d65549dd --- /dev/null +++ b/man/man3/tomo-Int.clamped.3 @@ -0,0 +1,36 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Int.clamped 3 2025-04-19T14:30:40.360382 "Tomo man-pages" +.SH NAME +Int.clamped \- Returns the given number clamped between two values so that it is within that range. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Int.clamped : func(x: Int, low: Int, high: Int -> Int)" +.fi + +.SH DESCRIPTION +Returns the given number clamped between two values so that it is within that range. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Int The integer to clamp. - +low Int The lowest value the result can take. - +high Int The highest value the result can take. - +.TE +.SH RETURN +The first argument clamped between the other two arguments. + +.SH EXAMPLES +.EX +>> (2).clamped(5, 10) += 5 +.EE diff --git a/man/man3/tomo-Int.factorial.3 b/man/man3/tomo-Int.factorial.3 new file mode 100644 index 00000000..0cbe1fb3 --- /dev/null +++ b/man/man3/tomo-Int.factorial.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Int.factorial 3 2025-04-19T14:30:40.360421 "Tomo man-pages" +.SH NAME +Int.factorial \- Computes the factorial of an integer. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Int.factorial : func(n: Int -> Text)" +.fi + +.SH DESCRIPTION +Computes the factorial of an integer. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +n Int The integer to compute the factorial of. - +.TE +.SH RETURN +The factorial of the given integer. + +.SH EXAMPLES +.EX +>> (10).factorial() += 3628800 +.EE diff --git a/man/man3/tomo-Int.format.3 b/man/man3/tomo-Int.format.3 new file mode 100644 index 00000000..afe76967 --- /dev/null +++ b/man/man3/tomo-Int.format.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Int.format 3 2025-04-19T14:30:40.360458 "Tomo man-pages" +.SH NAME +Int.format \- Formats an integer as a string with a specified number of digits. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Int.format : func(i: Int, digits: Int = 0 -> Text)" +.fi + +.SH DESCRIPTION +Formats an integer as a string with a specified number of digits. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +i Int The integer to be formatted. - +digits Int The minimum number of digits to which the integer should be padded. 0 +.TE +.SH RETURN +A string representation of the integer, padded to the specified number of digits. + +.SH EXAMPLES +.EX +>> (42).format(digits=5) += "00042" +.EE diff --git a/man/man3/tomo-Int.hex.3 b/man/man3/tomo-Int.hex.3 new file mode 100644 index 00000000..ded16562 --- /dev/null +++ b/man/man3/tomo-Int.hex.3 @@ -0,0 +1,37 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Int.hex 3 2025-04-19T14:30:40.360505 "Tomo man-pages" +.SH NAME +Int.hex \- Converts an integer to its hexadecimal representation. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Int.hex : func(i: Int, digits: Int = 0, uppercase: Bool = yes, prefix: Bool = yes -> Text)" +.fi + +.SH DESCRIPTION +Converts an integer to its hexadecimal representation. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +i Int The integer to be converted. - +digits Int The minimum number of digits in the output string. 0 +uppercase Bool Whether to use uppercase letters for hexadecimal digits. yes +prefix Bool Whether to include a "0x" prefix. yes +.TE +.SH RETURN +The hexadecimal string representation of the integer. + +.SH EXAMPLES +.EX +>> (255).hex(digits=4, uppercase=yes, prefix=yes) += "0x00FF" +.EE diff --git a/man/man3/tomo-Int.is_between.3 b/man/man3/tomo-Int.is_between.3 new file mode 100644 index 00000000..4c940ccd --- /dev/null +++ b/man/man3/tomo-Int.is_between.3 @@ -0,0 +1,40 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Int.is_between 3 2025-04-19T14:30:40.360548 "Tomo man-pages" +.SH NAME +Int.is_between \- Determines if an integer is between two numbers (inclusive). + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Int.is_between : func(x: Int, low: Int, high: Int -> Bool)" +.fi + +.SH DESCRIPTION +Determines if an integer is between two numbers (inclusive). + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Int The integer to be checked. - +low Int The lower bound to check (inclusive). - +high Int The upper bound to check (inclusive). - +.TE +.SH RETURN +`yes` if `low <= x and x <= high`, otherwise `no` + +.SH EXAMPLES +.EX +>> (7).is_between(1, 10) += yes +>> (7).is_between(100, 200) += no +>> (7).is_between(1, 7) += yes +.EE diff --git a/man/man3/tomo-Int.is_prime.3 b/man/man3/tomo-Int.is_prime.3 new file mode 100644 index 00000000..4cb59dd7 --- /dev/null +++ b/man/man3/tomo-Int.is_prime.3 @@ -0,0 +1,40 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Int.is_prime 3 2025-04-19T14:30:40.360587 "Tomo man-pages" +.SH NAME +Int.is_prime \- Determines if an integer is a prime number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Int.is_prime : func(x: Int, reps: Int = 50 -> Bool)" +.fi + +.SH DESCRIPTION +Determines if an integer is a prime number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Int The integer to be checked. - +reps Int The number of repetitions for primality tests. 50 +.TE +.SH RETURN +`yes` if `x` is a prime number, `no` otherwise. + +.SH NOTES +This function is _probabilistic_. With the default arguments, the chances of getting an incorrect answer are astronomically small (on the order of 10^(-30)). See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp) for more details. + +.SH EXAMPLES +.EX +>> (7).is_prime() += yes +>> (6).is_prime() += no +.EE diff --git a/man/man3/tomo-Int.next_prime.3 b/man/man3/tomo-Int.next_prime.3 new file mode 100644 index 00000000..7890d0bc --- /dev/null +++ b/man/man3/tomo-Int.next_prime.3 @@ -0,0 +1,37 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Int.next_prime 3 2025-04-19T14:30:40.360625 "Tomo man-pages" +.SH NAME +Int.next_prime \- Finds the next prime number greater than the given integer. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Int.next_prime : func(x: Int -> Int)" +.fi + +.SH DESCRIPTION +Finds the next prime number greater than the given integer. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Int The integer after which to find the next prime. - +.TE +.SH RETURN +The next prime number greater than `x`. + +.SH NOTES +This function is _probabilistic_, but the chances of getting an incorrect answer are astronomically small (on the order of 10^(-30)). See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp) for more details. + +.SH EXAMPLES +.EX +>> (11).next_prime() += 13 +.EE diff --git a/man/man3/tomo-Int.octal.3 b/man/man3/tomo-Int.octal.3 new file mode 100644 index 00000000..244e3320 --- /dev/null +++ b/man/man3/tomo-Int.octal.3 @@ -0,0 +1,36 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Int.octal 3 2025-04-19T14:30:40.360662 "Tomo man-pages" +.SH NAME +Int.octal \- Converts an integer to its octal representation. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Int.octal : func(i: Int, digits: Int = 0, prefix: Bool = yes -> Text)" +.fi + +.SH DESCRIPTION +Converts an integer to its octal representation. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +i Int The integer to be converted. - +digits Int The minimum number of digits in the output string. 0 +prefix Bool Whether to include a "0o" prefix. yes +.TE +.SH RETURN +The octal string representation of the integer. + +.SH EXAMPLES +.EX +>> (64).octal(digits=4, prefix=yes) += "0o0100" +.EE diff --git a/man/man3/tomo-Int.onward.3 b/man/man3/tomo-Int.onward.3 new file mode 100644 index 00000000..2cb295f9 --- /dev/null +++ b/man/man3/tomo-Int.onward.3 @@ -0,0 +1,39 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Int.onward 3 2025-04-19T14:30:40.360700 "Tomo man-pages" +.SH NAME +Int.onward \- Return an iterator that counts infinitely from the starting integer (with an optional step size). + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Int.onward : func(first: Int, step: Int = 1 -> Text)" +.fi + +.SH DESCRIPTION +Return an iterator that counts infinitely from the starting integer (with an optional step size). + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +first Int The starting integer. - +step Int The increment step size. 1 +.TE +.SH RETURN +An iterator function that counts onward from the starting integer. + +.SH EXAMPLES +.EX +nums : &[Int] = &[] +for i in (5).onward() +nums.insert(i) +stop if i == 10 +>> nums[] += [5, 6, 7, 8, 9, 10] +.EE diff --git a/man/man3/tomo-Int.parse.3 b/man/man3/tomo-Int.parse.3 new file mode 100644 index 00000000..adb64d95 --- /dev/null +++ b/man/man3/tomo-Int.parse.3 @@ -0,0 +1,44 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Int.parse 3 2025-04-19T14:30:40.360757 "Tomo man-pages" +.SH NAME +Int.parse \- Converts a text representation of an integer into an integer. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Int.parse : func(text: Text -> Int?)" +.fi + +.SH DESCRIPTION +Converts a text representation of an integer into an integer. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text containing the integer. - +.TE +.SH RETURN +The integer represented by the text. If the given text contains a value outside of the representable range or if the entire text can't be parsed as an integer, `none` will be returned. + +.SH EXAMPLES +.EX +>> Int.parse("123") += 123 : Int? +>> Int.parse("0xFF") += 255 : Int? + +# Can't parse: +>> Int.parse("asdf") += none : Int? + +# Outside valid range: +>> Int8.parse("9999999") += none : Int8? +.EE diff --git a/man/man3/tomo-Int.prev_prime.3 b/man/man3/tomo-Int.prev_prime.3 new file mode 100644 index 00000000..50c62575 --- /dev/null +++ b/man/man3/tomo-Int.prev_prime.3 @@ -0,0 +1,37 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Int.prev_prime 3 2025-04-19T14:30:40.360801 "Tomo man-pages" +.SH NAME +Int.prev_prime \- Finds the previous prime number less than the given integer. If there is no previous prime number (i.e. if a number less than `2` is provided), then the function will create a runtime error. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Int.prev_prime : func(x: Int -> Int?)" +.fi + +.SH DESCRIPTION +Finds the previous prime number less than the given integer. If there is no previous prime number (i.e. if a number less than `2` is provided), then the function will create a runtime error. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Int The integer before which to find the previous prime. - +.TE +.SH RETURN +The previous prime number less than `x`, or `none` if `x` is less than 2. + +.SH NOTES +This function is _probabilistic_, but the chances of getting an incorrect answer are astronomically small (on the order of 10^(-30)). See [the GNU MP docs](https://gmplib.org/manual/Number-Theoretic-Functions#index-mpz_005fprobab_005fprime_005fp) for more details. + +.SH EXAMPLES +.EX +>> (11).prev_prime() += 7 +.EE diff --git a/man/man3/tomo-Int.sqrt.3 b/man/man3/tomo-Int.sqrt.3 new file mode 100644 index 00000000..8e6aba1d --- /dev/null +++ b/man/man3/tomo-Int.sqrt.3 @@ -0,0 +1,36 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Int.sqrt 3 2025-04-19T14:30:40.360844 "Tomo man-pages" +.SH NAME +Int.sqrt \- Calculates the nearest square root of an integer. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Int.sqrt : func(x: Int -> Int)" +.fi + +.SH DESCRIPTION +Calculates the nearest square root of an integer. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Int The integer whose square root is to be calculated. - +.TE +.SH RETURN +The integer part of the square root of `x`. + +.SH EXAMPLES +.EX +>> (16).sqrt() += 4 +>> (17).sqrt() += 4 +.EE diff --git a/man/man3/tomo-Int.to.3 b/man/man3/tomo-Int.to.3 new file mode 100644 index 00000000..53b6b0ff --- /dev/null +++ b/man/man3/tomo-Int.to.3 @@ -0,0 +1,43 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Int.to 3 2025-04-19T14:30:40.360881 "Tomo man-pages" +.SH NAME +Int.to \- Returns an iterator function that iterates over the range of numbers specified. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Int.to : func(first: Int, last: Int, step: Int? = none -> func(->Int?))" +.fi + +.SH DESCRIPTION +Returns an iterator function that iterates over the range of numbers specified. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +first Int The starting value of the range. - +last Int The ending value of the range. - +step Int? An optional step size to use. If unspecified or `none`, the step will be inferred to be `+1` if `last >= first`, otherwise `-1`. none +.TE +.SH RETURN +An iterator function that returns each integer in the given range (inclusive). + +.SH EXAMPLES +.EX +>> (2).to(5) += func(->Int?) +>> [x for x in (2).to(5)] += [2, 3, 4, 5] +>> [x for x in (5).to(2)] += [5, 4, 3, 2] + +>> [x for x in (2).to(5, step=2)] += [2, 4] +.EE diff --git a/man/man3/tomo-List.binary_search.3 b/man/man3/tomo-List.binary_search.3 new file mode 100644 index 00000000..d5cbbad5 --- /dev/null +++ b/man/man3/tomo-List.binary_search.3 @@ -0,0 +1,41 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.binary_search 3 2025-04-19T14:30:40.360924 "Tomo man-pages" +.SH NAME +List.binary_search \- Performs a binary search on a sorted list. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.binary_search : func(list: [T], by: func(x,y:&T->Int32) = T.compare -> Int)" +.fi + +.SH DESCRIPTION +Performs a binary search on a sorted list. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list [T] The sorted list to search. - +by func(x,y:&T->Int32) The comparison function used to determine order. If not specified, the default comparison function for the item type will be used. T.compare +.TE +.SH RETURN +Assuming the input list is sorted according to the given comparison function, return the index where the given item would be inserted to maintain the sorted order. That is, if the item is found, return its index, otherwise return the place where it would be found if it were inserted and the list were sorted. + +.SH EXAMPLES +.EX +>> [1, 3, 5, 7, 9].binary_search(5) += 3 + +>> [1, 3, 5, 7, 9].binary_search(-999) += 1 + +>> [1, 3, 5, 7, 9].binary_search(999) += 6 +.EE diff --git a/man/man3/tomo-List.by.3 b/man/man3/tomo-List.by.3 new file mode 100644 index 00000000..eaefd4c3 --- /dev/null +++ b/man/man3/tomo-List.by.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.by 3 2025-04-19T14:30:40.360962 "Tomo man-pages" +.SH NAME +List.by \- Creates a new list with elements spaced by the specified step value. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.by : func(list: [T], step: Int -> [T])" +.fi + +.SH DESCRIPTION +Creates a new list with elements spaced by the specified step value. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list [T] The original list. - +step Int The step value for selecting elements. - +.TE +.SH RETURN +A new list with every `step`-th element from the original list. + +.SH EXAMPLES +.EX +>> [1, 2, 3, 4, 5, 6].by(2) += [1, 3, 5] +.EE diff --git a/man/man3/tomo-List.clear.3 b/man/man3/tomo-List.clear.3 new file mode 100644 index 00000000..687d03b2 --- /dev/null +++ b/man/man3/tomo-List.clear.3 @@ -0,0 +1,33 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.clear 3 2025-04-19T14:30:40.361001 "Tomo man-pages" +.SH NAME +List.clear \- Clears all elements from the list. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.clear : func(list: @[T] -> Void)" +.fi + +.SH DESCRIPTION +Clears all elements from the list. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list @[T] The mutable reference to the list to be cleared. - +.TE +.SH RETURN +Nothing. + +.SH EXAMPLES +.EX +>> my_list.clear() +.EE diff --git a/man/man3/tomo-List.counts.3 b/man/man3/tomo-List.counts.3 new file mode 100644 index 00000000..bffe397c --- /dev/null +++ b/man/man3/tomo-List.counts.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.counts 3 2025-04-19T14:30:40.361035 "Tomo man-pages" +.SH NAME +List.counts \- Counts the occurrences of each element in the list. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.counts : func(list: [T] -> {T=Int})" +.fi + +.SH DESCRIPTION +Counts the occurrences of each element in the list. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list [T] The list to count elements in. - +.TE +.SH RETURN +A table mapping each element to its count. + +.SH EXAMPLES +.EX +>> [10, 20, 30, 30, 30].counts() += {10=1, 20=1, 30=3} +.EE diff --git a/man/man3/tomo-List.find.3 b/man/man3/tomo-List.find.3 new file mode 100644 index 00000000..d1b29f38 --- /dev/null +++ b/man/man3/tomo-List.find.3 @@ -0,0 +1,38 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.find 3 2025-04-19T14:30:40.361070 "Tomo man-pages" +.SH NAME +List.find \- Finds the index of the first occurrence of an element (if any). + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.find : func(list: [T], target: T -> Int?)" +.fi + +.SH DESCRIPTION +Finds the index of the first occurrence of an element (if any). + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list [T] The list to search through. - +target T The item to search for. - +.TE +.SH RETURN +The index of the first occurrence or `!Int` if not found. + +.SH EXAMPLES +.EX +>> [10, 20, 30, 40, 50].find(20) += 2 : Int? + +>> [10, 20, 30, 40, 50].find(9999) += none : Int? +.EE diff --git a/man/man3/tomo-List.first.3 b/man/man3/tomo-List.first.3 new file mode 100644 index 00000000..4bde4a21 --- /dev/null +++ b/man/man3/tomo-List.first.3 @@ -0,0 +1,37 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.first 3 2025-04-19T14:30:40.361125 "Tomo man-pages" +.SH NAME +List.first \- Find the index of the first item that matches a predicate function (if any). + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.first : func(list: [T], predicate: func(item:&T -> Bool) -> Int)" +.fi + +.SH DESCRIPTION +Find the index of the first item that matches a predicate function (if any). + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list [T] The list to search through. - +predicate func(item:&T -> Bool) A function that returns `yes` if the item should be returned or `no` if it should not. - +.TE +.SH RETURN +Returns the index of the first item where the predicate is true or `!Int` if no item matches. + +.SH EXAMPLES +.EX +>> [4, 5, 6].find(func(i:&Int): i.is_prime()) += 5 : Int? +>> [4, 6, 8].find(func(i:&Int): i.is_prime()) += none : Int? +.EE diff --git a/man/man3/tomo-List.from.3 b/man/man3/tomo-List.from.3 new file mode 100644 index 00000000..0ee5faa4 --- /dev/null +++ b/man/man3/tomo-List.from.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.from 3 2025-04-19T14:30:40.361167 "Tomo man-pages" +.SH NAME +List.from \- Returns a slice of the list starting from a specified index. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.from : func(list: [T], first: Int -> [T])" +.fi + +.SH DESCRIPTION +Returns a slice of the list starting from a specified index. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list [T] The original list. - +first Int The index to start from. - +.TE +.SH RETURN +A new list starting from the specified index. + +.SH EXAMPLES +.EX +>> [10, 20, 30, 40, 50].from(3) += [30, 40, 50] +.EE diff --git a/man/man3/tomo-List.has.3 b/man/man3/tomo-List.has.3 new file mode 100644 index 00000000..694a3b6f --- /dev/null +++ b/man/man3/tomo-List.has.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.has 3 2025-04-19T14:30:40.361206 "Tomo man-pages" +.SH NAME +List.has \- Checks if the list has an element. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.has : func(list: [T], target: T -> Bool)" +.fi + +.SH DESCRIPTION +Checks if the list has an element. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list [T] The list to check. - +target T The element to check for. - +.TE +.SH RETURN +`yes` if the list has the element, `no` otherwise. + +.SH EXAMPLES +.EX +>> [10, 20, 30].has(20) += yes +.EE diff --git a/man/man3/tomo-List.heap_pop.3 b/man/man3/tomo-List.heap_pop.3 new file mode 100644 index 00000000..f0cce34d --- /dev/null +++ b/man/man3/tomo-List.heap_pop.3 @@ -0,0 +1,37 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.heap_pop 3 2025-04-19T14:30:40.361244 "Tomo man-pages" +.SH NAME +List.heap_pop \- Removes and returns the top element of a heap or `none` if the list is empty. By default, this is the *minimum* value in the heap. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.heap_pop : func(list: @[T], by: func(x,y:&T->Int32) = T.compare -> T?)" +.fi + +.SH DESCRIPTION +Removes and returns the top element of a heap or `none` if the list is empty. By default, this is the *minimum* value in the heap. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list @[T] The mutable reference to the heap. - +by func(x,y:&T->Int32) The comparison function used to determine order. If not specified, the default comparison function for the item type will be used. T.compare +.TE +.SH RETURN +The removed top element of the heap or `none` if the list is empty. + +.SH EXAMPLES +.EX +>> my_heap := [30, 10, 20] +>> my_heap.heapify() +>> my_heap.heap_pop() += 10 +.EE diff --git a/man/man3/tomo-List.heap_push.3 b/man/man3/tomo-List.heap_push.3 new file mode 100644 index 00000000..1de173c2 --- /dev/null +++ b/man/man3/tomo-List.heap_push.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.heap_push 3 2025-04-19T14:30:40.361282 "Tomo man-pages" +.SH NAME +List.heap_push \- Adds an element to the heap and maintains the heap property. By default, this is a *minimum* heap. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.heap_push : func(list: @[T], item: T, by = T.compare -> Void)" +.fi + +.SH DESCRIPTION +Adds an element to the heap and maintains the heap property. By default, this is a *minimum* heap. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list @[T] The mutable reference to the heap. - +item T The item to be added. - +by The comparison function used to determine order. If not specified, the default comparison function for the item type will be used. T.compare +.TE +.SH RETURN +Nothing. + +.SH EXAMPLES +.EX +>> my_heap.heap_push(10) +.EE diff --git a/man/man3/tomo-List.heapify.3 b/man/man3/tomo-List.heapify.3 new file mode 100644 index 00000000..f2df2674 --- /dev/null +++ b/man/man3/tomo-List.heapify.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.heapify 3 2025-04-19T14:30:40.361322 "Tomo man-pages" +.SH NAME +List.heapify \- Converts a list into a heap. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.heapify : func(list: @[T], by: func(x,y:&T->Int32) = T.compare -> Void)" +.fi + +.SH DESCRIPTION +Converts a list into a heap. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list @[T] The mutable reference to the list to be heapified. - +by func(x,y:&T->Int32) The comparison function used to determine order. If not specified, the default comparison function for the item type will be used. T.compare +.TE +.SH RETURN +Nothing. + +.SH EXAMPLES +.EX +>> my_heap := [30, 10, 20] +>> my_heap.heapify() +.EE diff --git a/man/man3/tomo-List.insert.3 b/man/man3/tomo-List.insert.3 new file mode 100644 index 00000000..dff1783d --- /dev/null +++ b/man/man3/tomo-List.insert.3 @@ -0,0 +1,45 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.insert 3 2025-04-19T14:30:40.361359 "Tomo man-pages" +.SH NAME +List.insert \- Inserts an element at a specified position in the list. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.insert : func(list: @[T], item: T, at: Int = 0 -> Void)" +.fi + +.SH DESCRIPTION +Inserts an element at a specified position in the list. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list @[T] The mutable reference to the list. - +item T The item to be inserted. - +at Int The index at which to insert the item. 0 +.TE +.SH RETURN +Nothing. + +.SH NOTES +Since indices are 1-indexed and negative indices mean "starting from the back", an index of `0` means "after the last item". + +.SH EXAMPLES +.EX +>> list := [10, 20] +>> list.insert(30) +>> list += [10, 20, 30] + +>> list.insert(999, at=2) +>> list += [10, 999, 20, 30] +.EE diff --git a/man/man3/tomo-List.insert_all.3 b/man/man3/tomo-List.insert_all.3 new file mode 100644 index 00000000..9f7289d4 --- /dev/null +++ b/man/man3/tomo-List.insert_all.3 @@ -0,0 +1,45 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.insert_all 3 2025-04-19T14:30:40.361398 "Tomo man-pages" +.SH NAME +List.insert_all \- Inserts a list of items at a specified position in the list. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.insert_all : func(list: @[T], items: [T], at: Int = 0 -> Void)" +.fi + +.SH DESCRIPTION +Inserts a list of items at a specified position in the list. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list @[T] The mutable reference to the list. - +items [T] The items to be inserted. - +at Int The index at which to insert the item. 0 +.TE +.SH RETURN +Nothing. + +.SH NOTES +Since indices are 1-indexed and negative indices mean "starting from the back", an index of `0` means "after the last item". + +.SH EXAMPLES +.EX +list := [10, 20] +list.insert_all([30, 40]) +>> list += [10, 20, 30, 40] + +list.insert_all([99, 100], at=2) +>> list += [10, 99, 100, 20, 30, 40] +.EE diff --git a/man/man3/tomo-List.pop.3 b/man/man3/tomo-List.pop.3 new file mode 100644 index 00000000..303ae439 --- /dev/null +++ b/man/man3/tomo-List.pop.3 @@ -0,0 +1,47 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.pop 3 2025-04-19T14:30:40.361436 "Tomo man-pages" +.SH NAME +List.pop \- Removes and returns an item from the list. If the given index is present in the list, the item at that index will be removed and the list will become one element shorter. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.pop : func(list: &[T], index: Int = -1 -> T?)" +.fi + +.SH DESCRIPTION +Removes and returns an item from the list. If the given index is present in the list, the item at that index will be removed and the list will become one element shorter. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list &[T] The list to remove an item from. - +index Int The index from which to remove the item. -1 +.TE +.SH RETURN +`none` if the list is empty or the given index does not exist in the list, otherwise the item at the given index. + +.SH NOTES +Since negative indices are counted from the back, the default behavior is to pop the last value. + +.SH EXAMPLES +.EX +>> list := [10, 20, 30, 40] + +>> list.pop() += 40 +>> list += &[10, 20, 30] + +>> list.pop(index=2) += 20 +>> list += &[10, 30] +.EE diff --git a/man/man3/tomo-List.random.3 b/man/man3/tomo-List.random.3 new file mode 100644 index 00000000..65355a73 --- /dev/null +++ b/man/man3/tomo-List.random.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.random 3 2025-04-19T14:30:40.361484 "Tomo man-pages" +.SH NAME +List.random \- Selects a random element from the list. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.random : func(list: [T], random: func(min,max:Int64->Int64)? = none -> T)" +.fi + +.SH DESCRIPTION +Selects a random element from the list. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list [T] The list from which to select a random element. - +random func(min,max:Int64->Int64)? If provided, this function will be used to get a random index in the list. Returned values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number generation) none +.TE +.SH RETURN +A random element from the list. + +.SH EXAMPLES +.EX +>> [10, 20, 30].random() += 20 +.EE diff --git a/man/man3/tomo-List.remove_at.3 b/man/man3/tomo-List.remove_at.3 new file mode 100644 index 00000000..241315a4 --- /dev/null +++ b/man/man3/tomo-List.remove_at.3 @@ -0,0 +1,45 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.remove_at 3 2025-04-19T14:30:40.361523 "Tomo man-pages" +.SH NAME +List.remove_at \- Removes elements from the list starting at a specified index. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.remove_at : func(list: @[T], at: Int = -1, count: Int = 1 -> Void)" +.fi + +.SH DESCRIPTION +Removes elements from the list starting at a specified index. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list @[T] The mutable reference to the list. - +at Int The index at which to start removing elements. -1 +count Int The number of elements to remove. 1 +.TE +.SH RETURN +Nothing. + +.SH NOTES +Since negative indices are counted from the back, the default behavior is to remove the last item. + +.SH EXAMPLES +.EX +list := [10, 20, 30, 40, 50] +list.remove_at(2) +>> list += [10, 30, 40, 50] + +list.remove_at(2, count=2) +>> list += [10, 50] +.EE diff --git a/man/man3/tomo-List.remove_item.3 b/man/man3/tomo-List.remove_item.3 new file mode 100644 index 00000000..5c4a2b32 --- /dev/null +++ b/man/man3/tomo-List.remove_item.3 @@ -0,0 +1,45 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.remove_item 3 2025-04-19T14:30:40.361566 "Tomo man-pages" +.SH NAME +List.remove_item \- Removes all occurrences of a specified item from the list. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.remove_item : func(list: @[T], item: T, max_count: Int = -1 -> Void)" +.fi + +.SH DESCRIPTION +Removes all occurrences of a specified item from the list. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list @[T] The mutable reference to the list. - +item T The item to be removed. - +max_count Int The maximum number of occurrences to remove. -1 +.TE +.SH RETURN +Nothing. + +.SH NOTES +A negative `max_count` means "remove all occurrences". + +.SH EXAMPLES +.EX +list := [10, 20, 10, 20, 30] +list.remove_item(10) +>> list += [20, 20, 30] + +list.remove_item(20, max_count=1) +>> list += [20, 30] +.EE diff --git a/man/man3/tomo-List.reversed.3 b/man/man3/tomo-List.reversed.3 new file mode 100644 index 00000000..dd0b2242 --- /dev/null +++ b/man/man3/tomo-List.reversed.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.reversed 3 2025-04-19T14:30:40.361612 "Tomo man-pages" +.SH NAME +List.reversed \- Returns a reversed slice of the list. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.reversed : func(list: [T] -> [T])" +.fi + +.SH DESCRIPTION +Returns a reversed slice of the list. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list [T] The list to be reversed. - +.TE +.SH RETURN +A slice of the list with elements in reverse order. + +.SH EXAMPLES +.EX +>> [10, 20, 30].reversed() += [30, 20, 10] +.EE diff --git a/man/man3/tomo-List.sample.3 b/man/man3/tomo-List.sample.3 new file mode 100644 index 00000000..a1142e95 --- /dev/null +++ b/man/man3/tomo-List.sample.3 @@ -0,0 +1,40 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.sample 3 2025-04-19T14:30:40.361676 "Tomo man-pages" +.SH NAME +List.sample \- Selects a sample of elements from the list, optionally with weighted probabilities. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.sample : func(list: [T], count: Int, weights: [Num]? = ![Num], random: func(->Num)? = none -> [T])" +.fi + +.SH DESCRIPTION +Selects a sample of elements from the list, optionally with weighted probabilities. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list [T] The list to sample from. - +count Int The number of elements to sample. - +weights [Num]? The probability weights for each element in the list. These values do not need to add up to any particular number, they are relative weights. If no weights are given, elements will be sampled with uniform probability. ![Num] +random func(->Num)? If provided, this function will be used to get random values for sampling the list. The provided function should return random numbers between `0.0` (inclusive) and `1.0` (exclusive). (Used for deterministic pseudorandom number generation) none +.TE +.SH RETURN +A list of sampled elements from the list. + +.SH ERRORS +Errors will be raised if any of the following conditions occurs: - The given list has no elements and `count >= 1` - `count < 0` (negative count) - The number of weights provided doesn't match the length of the list. - Any weight in the weights list is negative, infinite, or `NaN` - The sum of the given weights is zero (zero probability for every element). + +.SH EXAMPLES +.EX +>> [10, 20, 30].sample(2, weights=[90%, 5%, 5%]) += [10, 10] +.EE diff --git a/man/man3/tomo-List.shuffle.3 b/man/man3/tomo-List.shuffle.3 new file mode 100644 index 00000000..f6bf6dc4 --- /dev/null +++ b/man/man3/tomo-List.shuffle.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.shuffle 3 2025-04-19T14:30:40.361726 "Tomo man-pages" +.SH NAME +List.shuffle \- Shuffles the elements of the list in place. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.shuffle : func(list: @[T], random: func(min,max:Int64->Int64)? = none -> Void)" +.fi + +.SH DESCRIPTION +Shuffles the elements of the list in place. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list @[T] The mutable reference to the list to be shuffled. - +random func(min,max:Int64->Int64)? If provided, this function will be used to get a random index in the list. Returned values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number generation) none +.TE +.SH RETURN +Nothing. + +.SH EXAMPLES +.EX +>> list.shuffle() +.EE diff --git a/man/man3/tomo-List.shuffled.3 b/man/man3/tomo-List.shuffled.3 new file mode 100644 index 00000000..7f62ace8 --- /dev/null +++ b/man/man3/tomo-List.shuffled.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.shuffled 3 2025-04-19T14:30:40.361789 "Tomo man-pages" +.SH NAME +List.shuffled \- Creates a new list with elements shuffled. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.shuffled : func(list: [T], random: func(min,max:Int64->Int64)? = none -> [T])" +.fi + +.SH DESCRIPTION +Creates a new list with elements shuffled. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list [T] The list to be shuffled. - +random func(min,max:Int64->Int64)? If provided, this function will be used to get a random index in the list. Returned values must be between `min` and `max` (inclusive). (Used for deterministic pseudorandom number generation) none +.TE +.SH RETURN +A new list with shuffled elements. + +.SH EXAMPLES +.EX +>> [10, 20, 30, 40].shuffled() += [40, 10, 30, 20] +.EE diff --git a/man/man3/tomo-List.slice.3 b/man/man3/tomo-List.slice.3 new file mode 100644 index 00000000..8cd76a8d --- /dev/null +++ b/man/man3/tomo-List.slice.3 @@ -0,0 +1,39 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.slice 3 2025-04-19T14:30:40.361827 "Tomo man-pages" +.SH NAME +List.slice \- Returns a slice of the list spanning the given indices (inclusive). + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.slice : func(list: [T], from: Int, to: Int -> [T])" +.fi + +.SH DESCRIPTION +Returns a slice of the list spanning the given indices (inclusive). + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list [T] The original list. - +from Int The first index to include. - +to Int The last index to include. - +.TE +.SH RETURN +A new list spanning the given indices. Note: negative indices are counted from the back of the list, so `-1` refers to the last element, `-2` the second-to-last, and so on. + +.SH EXAMPLES +.EX +>> [10, 20, 30, 40, 50].slice(2, 4) += [20, 30, 40] + +>> [10, 20, 30, 40, 50].slice(-3, -2) += [30, 40] +.EE diff --git a/man/man3/tomo-List.sort.3 b/man/man3/tomo-List.sort.3 new file mode 100644 index 00000000..f8dac2a1 --- /dev/null +++ b/man/man3/tomo-List.sort.3 @@ -0,0 +1,41 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.sort 3 2025-04-19T14:30:40.361865 "Tomo man-pages" +.SH NAME +List.sort \- Sorts the elements of the list in place in ascending order (small to large). + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.sort : func(list: @[T], by = T.compare -> Void)" +.fi + +.SH DESCRIPTION +Sorts the elements of the list in place in ascending order (small to large). + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list @[T] The mutable reference to the list to be sorted. - +by The comparison function used to determine order. If not specified, the default comparison function for the item type will be used. T.compare +.TE +.SH RETURN +Nothing. + +.SH EXAMPLES +.EX +list := [40, 10, -30, 20] +list.sort() +>> list += [-30, 10, 20, 40] + +list.sort(func(a,b:&Int): a.abs() <> b.abs()) +>> list += [10, 20, -30, 40] +.EE diff --git a/man/man3/tomo-List.sorted.3 b/man/man3/tomo-List.sorted.3 new file mode 100644 index 00000000..05043cdc --- /dev/null +++ b/man/man3/tomo-List.sorted.3 @@ -0,0 +1,38 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.sorted 3 2025-04-19T14:30:40.361919 "Tomo man-pages" +.SH NAME +List.sorted \- Creates a new list with elements sorted. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.sorted : func(list: [T], by = T.compare -> [T])" +.fi + +.SH DESCRIPTION +Creates a new list with elements sorted. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list [T] The list to be sorted. - +by The comparison function used to determine order. If not specified, the default comparison function for the item type will be used. T.compare +.TE +.SH RETURN +A new list with sorted elements. + +.SH EXAMPLES +.EX +>> [40, 10, -30, 20].sorted() += [-30, 10, 20, 40] + +>> [40, 10, -30, 20].sorted(func(a,b:&Int): a.abs() <> b.abs()) += [10, 20, -30, 40] +.EE diff --git a/man/man3/tomo-List.to.3 b/man/man3/tomo-List.to.3 new file mode 100644 index 00000000..82143c0b --- /dev/null +++ b/man/man3/tomo-List.to.3 @@ -0,0 +1,38 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.to 3 2025-04-19T14:30:40.361956 "Tomo man-pages" +.SH NAME +List.to \- Returns a slice of the list from the start of the original list up to a specified index (inclusive). + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.to : func(list: [T], last: Int -> [T])" +.fi + +.SH DESCRIPTION +Returns a slice of the list from the start of the original list up to a specified index (inclusive). + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list [T] The original list. - +last Int The index up to which elements should be included. - +.TE +.SH RETURN +A new list containing elements from the start up to the specified index. + +.SH EXAMPLES +.EX +>> [10, 20, 30, 40, 50].to(3) += [10, 20, 30] + +>> [10, 20, 30, 40, 50].to(-2) += [10, 20, 30, 40] +.EE diff --git a/man/man3/tomo-List.unique.3 b/man/man3/tomo-List.unique.3 new file mode 100644 index 00000000..5beefe40 --- /dev/null +++ b/man/man3/tomo-List.unique.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH List.unique 3 2025-04-19T14:30:40.361993 "Tomo man-pages" +.SH NAME +List.unique \- Returns a Set that contains the unique elements of the list. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "List.unique : func(list: [T] -> |T|)" +.fi + +.SH DESCRIPTION +Returns a Set that contains the unique elements of the list. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +list [T] The list to process. - +.TE +.SH RETURN +A set containing only unique elements from the list. + +.SH EXAMPLES +.EX +>> [10, 20, 10, 10, 30].unique() += {10, 20, 30} +.EE diff --git a/man/man3/tomo-Num.1_PI.3 b/man/man3/tomo-Num.1_PI.3 new file mode 100644 index 00000000..3be0c785 --- /dev/null +++ b/man/man3/tomo-Num.1_PI.3 @@ -0,0 +1,18 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.1_PI 3 2025-04-19T14:30:40.364254 "Tomo man-pages" +.SH NAME +Num.1_PI \- The constant $\frac{1}{\pi}$. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI 'Num.1_PI : Num' +.fi + +.SH DESCRIPTION +The constant $\frac{1}{\pi}$. + diff --git a/man/man3/tomo-Num.2_PI.3 b/man/man3/tomo-Num.2_PI.3 new file mode 100644 index 00000000..688bec38 --- /dev/null +++ b/man/man3/tomo-Num.2_PI.3 @@ -0,0 +1,18 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.2_PI 3 2025-04-19T14:30:40.364287 "Tomo man-pages" +.SH NAME +Num.2_PI \- The constant $2 \times \pi$. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI 'Num.2_PI : Num' +.fi + +.SH DESCRIPTION +The constant $2 \times \pi$. + diff --git a/man/man3/tomo-Num.2_SQRTPI.3 b/man/man3/tomo-Num.2_SQRTPI.3 new file mode 100644 index 00000000..42470e67 --- /dev/null +++ b/man/man3/tomo-Num.2_SQRTPI.3 @@ -0,0 +1,18 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.2_SQRTPI 3 2025-04-19T14:30:40.364319 "Tomo man-pages" +.SH NAME +Num.2_SQRTPI \- The constant $2 \times \sqrt{\pi}$. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI 'Num.2_SQRTPI : Num' +.fi + +.SH DESCRIPTION +The constant $2 \times \sqrt{\pi}$. + diff --git a/man/man3/tomo-Num.E.3 b/man/man3/tomo-Num.E.3 new file mode 100644 index 00000000..9ee849aa --- /dev/null +++ b/man/man3/tomo-Num.E.3 @@ -0,0 +1,18 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.E 3 2025-04-19T14:30:40.364352 "Tomo man-pages" +.SH NAME +Num.E \- The base of the natural logarithm ($e$). + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI 'Num.E : Num' +.fi + +.SH DESCRIPTION +The base of the natural logarithm ($e$). + diff --git a/man/man3/tomo-Num.INF.3 b/man/man3/tomo-Num.INF.3 new file mode 100644 index 00000000..51520ce9 --- /dev/null +++ b/man/man3/tomo-Num.INF.3 @@ -0,0 +1,18 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.INF 3 2025-04-19T14:30:40.364384 "Tomo man-pages" +.SH NAME +Num.INF \- Positive infinity. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI 'Num.INF : Num' +.fi + +.SH DESCRIPTION +Positive infinity. + diff --git a/man/man3/tomo-Num.LN10.3 b/man/man3/tomo-Num.LN10.3 new file mode 100644 index 00000000..9905d365 --- /dev/null +++ b/man/man3/tomo-Num.LN10.3 @@ -0,0 +1,18 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.LN10 3 2025-04-19T14:30:40.364415 "Tomo man-pages" +.SH NAME +Num.LN10 \- The natural logarithm of 10. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI 'Num.LN10 : Num' +.fi + +.SH DESCRIPTION +The natural logarithm of 10. + diff --git a/man/man3/tomo-Num.LN2.3 b/man/man3/tomo-Num.LN2.3 new file mode 100644 index 00000000..e4963292 --- /dev/null +++ b/man/man3/tomo-Num.LN2.3 @@ -0,0 +1,18 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.LN2 3 2025-04-19T14:30:40.364450 "Tomo man-pages" +.SH NAME +Num.LN2 \- The natural logarithm of 2. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI 'Num.LN2 : Num' +.fi + +.SH DESCRIPTION +The natural logarithm of 2. + diff --git a/man/man3/tomo-Num.LOG2E.3 b/man/man3/tomo-Num.LOG2E.3 new file mode 100644 index 00000000..85cebf47 --- /dev/null +++ b/man/man3/tomo-Num.LOG2E.3 @@ -0,0 +1,18 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.LOG2E 3 2025-04-19T14:30:40.364491 "Tomo man-pages" +.SH NAME +Num.LOG2E \- The base 2 logarithm of $e$ + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI 'Num.LOG2E : Num' +.fi + +.SH DESCRIPTION +The base 2 logarithm of $e$ + diff --git a/man/man3/tomo-Num.PI.3 b/man/man3/tomo-Num.PI.3 new file mode 100644 index 00000000..2ed8035b --- /dev/null +++ b/man/man3/tomo-Num.PI.3 @@ -0,0 +1,18 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.PI 3 2025-04-19T14:30:40.364524 "Tomo man-pages" +.SH NAME +Num.PI \- Pi ($\pi$). + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI 'Num.PI : Num' +.fi + +.SH DESCRIPTION +Pi ($\pi$). + diff --git a/man/man3/tomo-Num.PI_2.3 b/man/man3/tomo-Num.PI_2.3 new file mode 100644 index 00000000..207d14ca --- /dev/null +++ b/man/man3/tomo-Num.PI_2.3 @@ -0,0 +1,18 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.PI_2 3 2025-04-19T14:30:40.364557 "Tomo man-pages" +.SH NAME +Num.PI_2 \- $\frac{\pi}{2}$ + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI 'Num.PI_2 : Num' +.fi + +.SH DESCRIPTION +$\frac{\pi}{2}$ + diff --git a/man/man3/tomo-Num.PI_4.3 b/man/man3/tomo-Num.PI_4.3 new file mode 100644 index 00000000..a98c455b --- /dev/null +++ b/man/man3/tomo-Num.PI_4.3 @@ -0,0 +1,18 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.PI_4 3 2025-04-19T14:30:40.364588 "Tomo man-pages" +.SH NAME +Num.PI_4 \- $\frac{\pi}{4}$ + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI 'Num.PI_4 : Num' +.fi + +.SH DESCRIPTION +$\frac{\pi}{4}$ + diff --git a/man/man3/tomo-Num.SQRT1_2.3 b/man/man3/tomo-Num.SQRT1_2.3 new file mode 100644 index 00000000..4ddfc6e0 --- /dev/null +++ b/man/man3/tomo-Num.SQRT1_2.3 @@ -0,0 +1,18 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.SQRT1_2 3 2025-04-19T14:30:40.364618 "Tomo man-pages" +.SH NAME +Num.SQRT1_2 \- $\sqrt{\frac{1}{2}}$ + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI 'Num.SQRT1_2 : Num' +.fi + +.SH DESCRIPTION +$\sqrt{\frac{1}{2}}$ + diff --git a/man/man3/tomo-Num.SQRT2.3 b/man/man3/tomo-Num.SQRT2.3 new file mode 100644 index 00000000..21c62073 --- /dev/null +++ b/man/man3/tomo-Num.SQRT2.3 @@ -0,0 +1,18 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.SQRT2 3 2025-04-19T14:30:40.364647 "Tomo man-pages" +.SH NAME +Num.SQRT2 \- $\sqrt{2}$ + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI 'Num.SQRT2 : Num' +.fi + +.SH DESCRIPTION +$\sqrt{2}$ + diff --git a/man/man3/tomo-Num.TAU.3 b/man/man3/tomo-Num.TAU.3 new file mode 100644 index 00000000..d22a5e99 --- /dev/null +++ b/man/man3/tomo-Num.TAU.3 @@ -0,0 +1,18 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.TAU 3 2025-04-19T14:30:40.364676 "Tomo man-pages" +.SH NAME +Num.TAU \- Tau ($2 \times \pi$) + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI 'Num.TAU : Num' +.fi + +.SH DESCRIPTION +Tau ($2 \times \pi$) + diff --git a/man/man3/tomo-Num.abs.3 b/man/man3/tomo-Num.abs.3 new file mode 100644 index 00000000..fa438fd4 --- /dev/null +++ b/man/man3/tomo-Num.abs.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.abs 3 2025-04-19T14:30:40.362029 "Tomo man-pages" +.SH NAME +Num.abs \- Calculates the absolute value of a number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.abs : func(n: Num -> Num)" +.fi + +.SH DESCRIPTION +Calculates the absolute value of a number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +n Num The number whose absolute value is to be computed. - +.TE +.SH RETURN +The absolute value of `n`. + +.SH EXAMPLES +.EX +>> (-3.5).abs() += 3.5 +.EE diff --git a/man/man3/tomo-Num.acos.3 b/man/man3/tomo-Num.acos.3 new file mode 100644 index 00000000..74ed1f90 --- /dev/null +++ b/man/man3/tomo-Num.acos.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.acos 3 2025-04-19T14:30:40.362066 "Tomo man-pages" +.SH NAME +Num.acos \- Computes the arc cosine of a number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.acos : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the arc cosine of a number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number for which the arc cosine is to be calculated. - +.TE +.SH RETURN +The arc cosine of `x` in radians. + +.SH EXAMPLES +.EX +>> (0.0).acos() // -> (π/2) += 1.5708 +.EE diff --git a/man/man3/tomo-Num.acosh.3 b/man/man3/tomo-Num.acosh.3 new file mode 100644 index 00000000..13eea6ed --- /dev/null +++ b/man/man3/tomo-Num.acosh.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.acosh 3 2025-04-19T14:30:40.362105 "Tomo man-pages" +.SH NAME +Num.acosh \- Computes the inverse hyperbolic cosine of a number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.acosh : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the inverse hyperbolic cosine of a number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number for which the inverse hyperbolic cosine is to be calculated. - +.TE +.SH RETURN +The inverse hyperbolic cosine of `x`. + +.SH EXAMPLES +.EX +>> (1.0).acosh() += 0 +.EE diff --git a/man/man3/tomo-Num.asin.3 b/man/man3/tomo-Num.asin.3 new file mode 100644 index 00000000..76fbc1fd --- /dev/null +++ b/man/man3/tomo-Num.asin.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.asin 3 2025-04-19T14:30:40.362141 "Tomo man-pages" +.SH NAME +Num.asin \- Computes the arc sine of a number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.asin : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the arc sine of a number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number for which the arc sine is to be calculated. - +.TE +.SH RETURN +The arc sine of `x` in radians. + +.SH EXAMPLES +.EX +>> (0.5).asin() // -> (π/6) += 0.5236 +.EE diff --git a/man/man3/tomo-Num.asinh.3 b/man/man3/tomo-Num.asinh.3 new file mode 100644 index 00000000..06fcd4a5 --- /dev/null +++ b/man/man3/tomo-Num.asinh.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.asinh 3 2025-04-19T14:30:40.362177 "Tomo man-pages" +.SH NAME +Num.asinh \- Computes the inverse hyperbolic sine of a number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.asinh : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the inverse hyperbolic sine of a number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number for which the inverse hyperbolic sine is to be calculated. - +.TE +.SH RETURN +The inverse hyperbolic sine of `x`. + +.SH EXAMPLES +.EX +>> (0.0).asinh() += 0 +.EE diff --git a/man/man3/tomo-Num.atan.3 b/man/man3/tomo-Num.atan.3 new file mode 100644 index 00000000..ca041ba2 --- /dev/null +++ b/man/man3/tomo-Num.atan.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.atan 3 2025-04-19T14:30:40.362211 "Tomo man-pages" +.SH NAME +Num.atan \- Computes the arc tangent of a number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.atan : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the arc tangent of a number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number for which the arc tangent is to be calculated. - +.TE +.SH RETURN +The arc tangent of `x` in radians. + +.SH EXAMPLES +.EX +>> (1.0).atan() // -> (π/4) += 0.7854 +.EE diff --git a/man/man3/tomo-Num.atan2.3 b/man/man3/tomo-Num.atan2.3 new file mode 100644 index 00000000..25423767 --- /dev/null +++ b/man/man3/tomo-Num.atan2.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.atan2 3 2025-04-19T14:30:40.362246 "Tomo man-pages" +.SH NAME +Num.atan2 \- Computes the arc tangent of the quotient of two numbers. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.atan2 : func(x: Num, y: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the arc tangent of the quotient of two numbers. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The numerator. - +y Num The denominator. - +.TE +.SH RETURN +The arc tangent of `x/y` in radians. + +.SH EXAMPLES +.EX +>> Num.atan2(1, 1) // -> (π/4) += 0.7854 +.EE diff --git a/man/man3/tomo-Num.atanh.3 b/man/man3/tomo-Num.atanh.3 new file mode 100644 index 00000000..7618a3ae --- /dev/null +++ b/man/man3/tomo-Num.atanh.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.atanh 3 2025-04-19T14:30:40.362303 "Tomo man-pages" +.SH NAME +Num.atanh \- Computes the inverse hyperbolic tangent of a number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.atanh : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the inverse hyperbolic tangent of a number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number for which the inverse hyperbolic tangent is to be calculated. - +.TE +.SH RETURN +The inverse hyperbolic tangent of `x`. + +.SH EXAMPLES +.EX +>> (0.5).atanh() += 0.5493 +.EE diff --git a/man/man3/tomo-Num.cbrt.3 b/man/man3/tomo-Num.cbrt.3 new file mode 100644 index 00000000..91d5b975 --- /dev/null +++ b/man/man3/tomo-Num.cbrt.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.cbrt 3 2025-04-19T14:30:40.362342 "Tomo man-pages" +.SH NAME +Num.cbrt \- Computes the cube root of a number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.cbrt : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the cube root of a number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number for which the cube root is to be calculated. - +.TE +.SH RETURN +The cube root of `x`. + +.SH EXAMPLES +.EX +>> (27.0).cbrt() += 3 +.EE diff --git a/man/man3/tomo-Num.ceil.3 b/man/man3/tomo-Num.ceil.3 new file mode 100644 index 00000000..ee5abc83 --- /dev/null +++ b/man/man3/tomo-Num.ceil.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.ceil 3 2025-04-19T14:30:40.362380 "Tomo man-pages" +.SH NAME +Num.ceil \- Rounds a number up to the nearest integer. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.ceil : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Rounds a number up to the nearest integer. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number to be rounded up. - +.TE +.SH RETURN +The smallest integer greater than or equal to `x`. + +.SH EXAMPLES +.EX +>> (3.2).ceil() += 4 +.EE diff --git a/man/man3/tomo-Num.clamped.3 b/man/man3/tomo-Num.clamped.3 new file mode 100644 index 00000000..36eefe7f --- /dev/null +++ b/man/man3/tomo-Num.clamped.3 @@ -0,0 +1,36 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.clamped 3 2025-04-19T14:30:40.362416 "Tomo man-pages" +.SH NAME +Num.clamped \- Returns the given number clamped between two values so that it is within that range. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.clamped : func(x: Num, low: Num, high: Num -> Num)" +.fi + +.SH DESCRIPTION +Returns the given number clamped between two values so that it is within that range. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number to clamp. - +low Num The lowest value the result can take. - +high Num The highest value the result can take. - +.TE +.SH RETURN +The first argument clamped between the other two arguments. + +.SH EXAMPLES +.EX +>> (2.5).clamped(5.5, 10.5) += 5.5 +.EE diff --git a/man/man3/tomo-Num.copysign.3 b/man/man3/tomo-Num.copysign.3 new file mode 100644 index 00000000..b20194b1 --- /dev/null +++ b/man/man3/tomo-Num.copysign.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.copysign 3 2025-04-19T14:30:40.362460 "Tomo man-pages" +.SH NAME +Num.copysign \- Copies the sign of one number to another. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.copysign : func(x: Num, y: Num -> Num)" +.fi + +.SH DESCRIPTION +Copies the sign of one number to another. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number whose magnitude will be copied. - +y Num The number whose sign will be copied. - +.TE +.SH RETURN +A number with the magnitude of `x` and the sign of `y`. + +.SH EXAMPLES +.EX +>> (3.0).copysign(-1) += -3 +.EE diff --git a/man/man3/tomo-Num.cos.3 b/man/man3/tomo-Num.cos.3 new file mode 100644 index 00000000..4da01be3 --- /dev/null +++ b/man/man3/tomo-Num.cos.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.cos 3 2025-04-19T14:30:40.362505 "Tomo man-pages" +.SH NAME +Num.cos \- Computes the cosine of a number (angle in radians). + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.cos : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the cosine of a number (angle in radians). + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The angle in radians. - +.TE +.SH RETURN +The cosine of `x`. + +.SH EXAMPLES +.EX +>> (0.0).cos() += 1 +.EE diff --git a/man/man3/tomo-Num.cosh.3 b/man/man3/tomo-Num.cosh.3 new file mode 100644 index 00000000..577b2f08 --- /dev/null +++ b/man/man3/tomo-Num.cosh.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.cosh 3 2025-04-19T14:30:40.362548 "Tomo man-pages" +.SH NAME +Num.cosh \- Computes the hyperbolic cosine of a number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.cosh : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the hyperbolic cosine of a number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number for which the hyperbolic cosine is to be calculated. - +.TE +.SH RETURN +The hyperbolic cosine of `x`. + +.SH EXAMPLES +.EX +>> (0.0).cosh() += 1 +.EE diff --git a/man/man3/tomo-Num.erf.3 b/man/man3/tomo-Num.erf.3 new file mode 100644 index 00000000..0ed7401d --- /dev/null +++ b/man/man3/tomo-Num.erf.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.erf 3 2025-04-19T14:30:40.362584 "Tomo man-pages" +.SH NAME +Num.erf \- Computes the error function of a number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.erf : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the error function of a number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number for which the error function is to be calculated. - +.TE +.SH RETURN +The error function of `x`. + +.SH EXAMPLES +.EX +>> (0.0).erf() += 0 +.EE diff --git a/man/man3/tomo-Num.erfc.3 b/man/man3/tomo-Num.erfc.3 new file mode 100644 index 00000000..c392f051 --- /dev/null +++ b/man/man3/tomo-Num.erfc.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.erfc 3 2025-04-19T14:30:40.362619 "Tomo man-pages" +.SH NAME +Num.erfc \- Computes the complementary error function of a number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.erfc : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the complementary error function of a number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number for which the complementary error function is to be calculated. - +.TE +.SH RETURN +The complementary error function of `x`. + +.SH EXAMPLES +.EX +>> (0.0).erfc() += 1 +.EE diff --git a/man/man3/tomo-Num.exp.3 b/man/man3/tomo-Num.exp.3 new file mode 100644 index 00000000..91de43a3 --- /dev/null +++ b/man/man3/tomo-Num.exp.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.exp 3 2025-04-19T14:30:40.362655 "Tomo man-pages" +.SH NAME +Num.exp \- Computes the exponential function $e^x$ for a number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.exp : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the exponential function $e^x$ for a number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The exponent. - +.TE +.SH RETURN +The value of $e^x$. + +.SH EXAMPLES +.EX +>> (1.0).exp() += 2.7183 +.EE diff --git a/man/man3/tomo-Num.exp2.3 b/man/man3/tomo-Num.exp2.3 new file mode 100644 index 00000000..ecebc8d0 --- /dev/null +++ b/man/man3/tomo-Num.exp2.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.exp2 3 2025-04-19T14:30:40.362690 "Tomo man-pages" +.SH NAME +Num.exp2 \- Computes $2^x$ for a number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.exp2 : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes $2^x$ for a number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The exponent. - +.TE +.SH RETURN +The value of $2^x$. + +.SH EXAMPLES +.EX +>> (3.0).exp2() += 8 +.EE diff --git a/man/man3/tomo-Num.expm1.3 b/man/man3/tomo-Num.expm1.3 new file mode 100644 index 00000000..617735e4 --- /dev/null +++ b/man/man3/tomo-Num.expm1.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.expm1 3 2025-04-19T14:30:40.362725 "Tomo man-pages" +.SH NAME +Num.expm1 \- Computes $e^x - 1$ for a number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.expm1 : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes $e^x - 1$ for a number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The exponent. - +.TE +.SH RETURN +The value of $e^x - 1$. + +.SH EXAMPLES +.EX +>> (1.0).expm1() += 1.7183 +.EE diff --git a/man/man3/tomo-Num.fdim.3 b/man/man3/tomo-Num.fdim.3 new file mode 100644 index 00000000..bd893aed --- /dev/null +++ b/man/man3/tomo-Num.fdim.3 @@ -0,0 +1,37 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.fdim 3 2025-04-19T14:30:40.362760 "Tomo man-pages" +.SH NAME +Num.fdim \- Computes the positive difference between two numbers. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.fdim : func(x: Num, y: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the positive difference between two numbers. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The first number. - +y Num The second number. - +.TE +.SH RETURN +The positive difference $\max(0, x - y)$. + +.SH EXAMPLES +.EX +fd + +>> (5.0).fdim(3) += 2 +.EE diff --git a/man/man3/tomo-Num.floor.3 b/man/man3/tomo-Num.floor.3 new file mode 100644 index 00000000..8daffc44 --- /dev/null +++ b/man/man3/tomo-Num.floor.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.floor 3 2025-04-19T14:30:40.362796 "Tomo man-pages" +.SH NAME +Num.floor \- Rounds a number down to the nearest integer. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.floor : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Rounds a number down to the nearest integer. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number to be rounded down. - +.TE +.SH RETURN +The largest integer less than or equal to `x`. + +.SH EXAMPLES +.EX +>> (3.7).floor() += 3 +.EE diff --git a/man/man3/tomo-Num.format.3 b/man/man3/tomo-Num.format.3 new file mode 100644 index 00000000..eedd87a4 --- /dev/null +++ b/man/man3/tomo-Num.format.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.format 3 2025-04-19T14:30:40.362831 "Tomo man-pages" +.SH NAME +Num.format \- Formats a number as a text with a specified precision. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.format : func(n: Num, precision: Int = 0 -> Text)" +.fi + +.SH DESCRIPTION +Formats a number as a text with a specified precision. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +n Num The number to be formatted. - +precision Int The number of decimal places. Default is `0`. 0 +.TE +.SH RETURN +A text representation of the number with the specified precision. + +.SH EXAMPLES +.EX +>> (3.14159).format(precision=2) += "3.14" +.EE diff --git a/man/man3/tomo-Num.hypot.3 b/man/man3/tomo-Num.hypot.3 new file mode 100644 index 00000000..c38e05d7 --- /dev/null +++ b/man/man3/tomo-Num.hypot.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.hypot 3 2025-04-19T14:30:40.362867 "Tomo man-pages" +.SH NAME +Num.hypot \- Computes the Euclidean norm, $\sqrt{x^2 + y^2}$, of two numbers. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.hypot : func(x: Num, y: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the Euclidean norm, $\sqrt{x^2 + y^2}$, of two numbers. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The first number. - +y Num The second number. - +.TE +.SH RETURN +The Euclidean norm of `x` and `y`. + +.SH EXAMPLES +.EX +>> Num.hypot(3, 4) += 5 +.EE diff --git a/man/man3/tomo-Num.is_between.3 b/man/man3/tomo-Num.is_between.3 new file mode 100644 index 00000000..5b008cbb --- /dev/null +++ b/man/man3/tomo-Num.is_between.3 @@ -0,0 +1,40 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.is_between 3 2025-04-19T14:30:40.362934 "Tomo man-pages" +.SH NAME +Num.is_between \- Determines if a number is between two numbers (inclusive). + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.is_between : func(x: Num, low: Num, high: Num -> Bool)" +.fi + +.SH DESCRIPTION +Determines if a number is between two numbers (inclusive). + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The integer to be checked. - +low Num The lower bound to check (inclusive). - +high Num The upper bound to check (inclusive). - +.TE +.SH RETURN +`yes` if `low <= x and x <= high`, otherwise `no` + +.SH EXAMPLES +.EX +>> (7.5).is_between(1, 10) += yes +>> (7.5).is_between(100, 200) += no +>> (7.5).is_between(1, 7.5) += yes +.EE diff --git a/man/man3/tomo-Num.isfinite.3 b/man/man3/tomo-Num.isfinite.3 new file mode 100644 index 00000000..1e0f2b73 --- /dev/null +++ b/man/man3/tomo-Num.isfinite.3 @@ -0,0 +1,36 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.isfinite 3 2025-04-19T14:30:40.362901 "Tomo man-pages" +.SH NAME +Num.isfinite \- Checks if a number is finite. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.isfinite : func(n: Num -> Bool)" +.fi + +.SH DESCRIPTION +Checks if a number is finite. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +n Num The number to be checked. - +.TE +.SH RETURN +`yes` if `n` is finite, `no` otherwise. + +.SH EXAMPLES +.EX +>> (1.0).isfinite() += yes +>> Num.INF.isfinite() += no +.EE diff --git a/man/man3/tomo-Num.isinf.3 b/man/man3/tomo-Num.isinf.3 new file mode 100644 index 00000000..225ad548 --- /dev/null +++ b/man/man3/tomo-Num.isinf.3 @@ -0,0 +1,36 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.isinf 3 2025-04-19T14:30:40.363007 "Tomo man-pages" +.SH NAME +Num.isinf \- Checks if a number is infinite. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.isinf : func(n: Num -> Bool)" +.fi + +.SH DESCRIPTION +Checks if a number is infinite. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +n Num The number to be checked. - +.TE +.SH RETURN +`yes` if `n` is infinite, `no` otherwise. + +.SH EXAMPLES +.EX +>> Num.INF.isinf() += yes +>> (1.0).isinf() += no +.EE diff --git a/man/man3/tomo-Num.j0.3 b/man/man3/tomo-Num.j0.3 new file mode 100644 index 00000000..bef1a41b --- /dev/null +++ b/man/man3/tomo-Num.j0.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.j0 3 2025-04-19T14:30:40.363075 "Tomo man-pages" +.SH NAME +Num.j0 \- Computes the Bessel function of the first kind of order 0. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.j0 : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the Bessel function of the first kind of order 0. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number for which the Bessel function is to be calculated. - +.TE +.SH RETURN +The Bessel function of the first kind of order 0 of `x`. + +.SH EXAMPLES +.EX +>> (0.0).j0() += 1 +.EE diff --git a/man/man3/tomo-Num.j1.3 b/man/man3/tomo-Num.j1.3 new file mode 100644 index 00000000..b1d09e8c --- /dev/null +++ b/man/man3/tomo-Num.j1.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.j1 3 2025-04-19T14:30:40.363115 "Tomo man-pages" +.SH NAME +Num.j1 \- Computes the Bessel function of the first kind of order 1. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.j1 : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the Bessel function of the first kind of order 1. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number for which the Bessel function is to be calculated. - +.TE +.SH RETURN +The Bessel function of the first kind of order 1 of `x`. + +.SH EXAMPLES +.EX +>> (0.0).j1() += 0 +.EE diff --git a/man/man3/tomo-Num.log.3 b/man/man3/tomo-Num.log.3 new file mode 100644 index 00000000..322de2e6 --- /dev/null +++ b/man/man3/tomo-Num.log.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.log 3 2025-04-19T14:30:40.363156 "Tomo man-pages" +.SH NAME +Num.log \- Computes the natural logarithm (base $e$) of a number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.log : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the natural logarithm (base $e$) of a number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number for which the natural logarithm is to be calculated. - +.TE +.SH RETURN +The natural logarithm of `x`. + +.SH EXAMPLES +.EX +>> Num.E.log() += 1 +.EE diff --git a/man/man3/tomo-Num.log10.3 b/man/man3/tomo-Num.log10.3 new file mode 100644 index 00000000..accf2234 --- /dev/null +++ b/man/man3/tomo-Num.log10.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.log10 3 2025-04-19T14:30:40.363192 "Tomo man-pages" +.SH NAME +Num.log10 \- Computes the base-10 logarithm of a number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.log10 : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the base-10 logarithm of a number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number for which the base-10 logarithm is to be calculated. - +.TE +.SH RETURN +The base-10 logarithm of `x`. + +.SH EXAMPLES +.EX +>> (100.0).log10() += 2 +.EE diff --git a/man/man3/tomo-Num.log1p.3 b/man/man3/tomo-Num.log1p.3 new file mode 100644 index 00000000..0dcf77f2 --- /dev/null +++ b/man/man3/tomo-Num.log1p.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.log1p 3 2025-04-19T14:30:40.363229 "Tomo man-pages" +.SH NAME +Num.log1p \- Computes $\log(1 + x)$ for a number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.log1p : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes $\log(1 + x)$ for a number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number for which $\log(1 + x)$ is to be calculated. - +.TE +.SH RETURN +The value of $\log(1 + x)$. + +.SH EXAMPLES +.EX +>> (1.0).log1p() += 0.6931 +.EE diff --git a/man/man3/tomo-Num.log2.3 b/man/man3/tomo-Num.log2.3 new file mode 100644 index 00000000..fd40282d --- /dev/null +++ b/man/man3/tomo-Num.log2.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.log2 3 2025-04-19T14:30:40.363268 "Tomo man-pages" +.SH NAME +Num.log2 \- Computes the base-2 logarithm of a number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.log2 : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the base-2 logarithm of a number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number for which the base-2 logarithm is to be calculated. - +.TE +.SH RETURN +The base-2 logarithm of `x`. + +.SH EXAMPLES +.EX +>> (8.0).log2() += 3 +.EE diff --git a/man/man3/tomo-Num.logb.3 b/man/man3/tomo-Num.logb.3 new file mode 100644 index 00000000..a13caa32 --- /dev/null +++ b/man/man3/tomo-Num.logb.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.logb 3 2025-04-19T14:30:40.363303 "Tomo man-pages" +.SH NAME +Num.logb \- Computes the binary exponent (base-2 logarithm) of a number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.logb : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the binary exponent (base-2 logarithm) of a number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number for which the binary exponent is to be calculated. - +.TE +.SH RETURN +The binary exponent of `x`. + +.SH EXAMPLES +.EX +>> (8.0).logb() += 3 +.EE diff --git a/man/man3/tomo-Num.mix.3 b/man/man3/tomo-Num.mix.3 new file mode 100644 index 00000000..804f0746 --- /dev/null +++ b/man/man3/tomo-Num.mix.3 @@ -0,0 +1,38 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.mix 3 2025-04-19T14:30:40.363337 "Tomo man-pages" +.SH NAME +Num.mix \- Interpolates between two numbers based on a given amount. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.mix : func(amount: Num, x: Num, y: Num -> Num)" +.fi + +.SH DESCRIPTION +Interpolates between two numbers based on a given amount. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +amount Num The interpolation factor (between `0` and `1`). - +x Num The starting number. - +y Num The ending number. - +.TE +.SH RETURN +The interpolated number between `x` and `y` based on `amount`. + +.SH EXAMPLES +.EX +>> (0.5).mix(10, 20) += 15 +>> (0.25).mix(10, 20) += 12.5 +.EE diff --git a/man/man3/tomo-Num.near.3 b/man/man3/tomo-Num.near.3 new file mode 100644 index 00000000..934e47cf --- /dev/null +++ b/man/man3/tomo-Num.near.3 @@ -0,0 +1,43 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.near 3 2025-04-19T14:30:40.363375 "Tomo man-pages" +.SH NAME +Num.near \- Checks if two numbers are approximately equal within specified tolerances. If two numbers are within an absolute difference or the ratio between the two is small enough, they are considered near each other. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.near : func(x: Num, y: Num, ratio: Num = 1e-9, min_epsilon: Num = 1e-9 -> Bool)" +.fi + +.SH DESCRIPTION +Checks if two numbers are approximately equal within specified tolerances. If two numbers are within an absolute difference or the ratio between the two is small enough, they are considered near each other. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The first number. - +y Num The second number. - +ratio Num The relative tolerance. Default is `1e-9`. 1e-9 +min_epsilon Num The absolute tolerance. Default is `1e-9`. 1e-9 +.TE +.SH RETURN +`yes` if `x` and `y` are approximately equal within the specified tolerances, `no` otherwise. + +.SH EXAMPLES +.EX +>> (1.0).near(1.000000001) += yes + +>> (100.0).near(110, ratio=0.1) += yes + +>> (5.0).near(5.1, min_epsilon=0.1) += yes +.EE diff --git a/man/man3/tomo-Num.nextafter.3 b/man/man3/tomo-Num.nextafter.3 new file mode 100644 index 00000000..c581e700 --- /dev/null +++ b/man/man3/tomo-Num.nextafter.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.nextafter 3 2025-04-19T14:30:40.363421 "Tomo man-pages" +.SH NAME +Num.nextafter \- Computes the next representable value after a given number towards a specified direction. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.nextafter : func(x: Num, y: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the next representable value after a given number towards a specified direction. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The starting number. - +y Num The direction towards which to find the next representable value. - +.TE +.SH RETURN +The next representable value after `x` in the direction of `y`. + +.SH EXAMPLES +.EX +>> (1.0).nextafter(1.1) += 1.0000000000000002 +.EE diff --git a/man/man3/tomo-Num.parse.3 b/man/man3/tomo-Num.parse.3 new file mode 100644 index 00000000..79211e96 --- /dev/null +++ b/man/man3/tomo-Num.parse.3 @@ -0,0 +1,36 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.parse 3 2025-04-19T14:30:40.363458 "Tomo man-pages" +.SH NAME +Num.parse \- Converts a text representation of a number into a floating-point number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.parse : func(text: Text -> Num?)" +.fi + +.SH DESCRIPTION +Converts a text representation of a number into a floating-point number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text containing the number. - +.TE +.SH RETURN +The number represented by the text or `none` if the entire text can't be parsed as a number. + +.SH EXAMPLES +.EX +>> Num.parse("3.14") += 3.14 +>> Num.parse("1e3") += 1000 +.EE diff --git a/man/man3/tomo-Num.percent.3 b/man/man3/tomo-Num.percent.3 new file mode 100644 index 00000000..d85f86d0 --- /dev/null +++ b/man/man3/tomo-Num.percent.3 @@ -0,0 +1,37 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.percent 3 2025-04-19T14:30:40.363501 "Tomo man-pages" +.SH NAME +Num.percent \- Convert a number into a percentage text with a percent sign. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.percent : func(n: Num, precision: Int = 0 -> Text)" +.fi + +.SH DESCRIPTION +Convert a number into a percentage text with a percent sign. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +n Num The number to be converted to a percent. - +precision Int The number of decimal places. Default is `0`. 0 +.TE +.SH RETURN +A text representation of the number as a percentage with a percent sign. + +.SH EXAMPLES +.EX +>> (0.5).percent() += "50%" +>> (1./3.).percent(2) += "33.33%" +.EE diff --git a/man/man3/tomo-Num.rint.3 b/man/man3/tomo-Num.rint.3 new file mode 100644 index 00000000..0cef35e2 --- /dev/null +++ b/man/man3/tomo-Num.rint.3 @@ -0,0 +1,36 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.rint 3 2025-04-19T14:30:40.363539 "Tomo man-pages" +.SH NAME +Num.rint \- Rounds a number to the nearest integer, with ties rounded to the nearest even integer. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.rint : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Rounds a number to the nearest integer, with ties rounded to the nearest even integer. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number to be rounded. - +.TE +.SH RETURN +The nearest integer value of `x`. + +.SH EXAMPLES +.EX +>> (3.5).rint() += 4 +>> (2.5).rint() += 2 +.EE diff --git a/man/man3/tomo-Num.round.3 b/man/man3/tomo-Num.round.3 new file mode 100644 index 00000000..c951503a --- /dev/null +++ b/man/man3/tomo-Num.round.3 @@ -0,0 +1,36 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.round 3 2025-04-19T14:30:40.363582 "Tomo man-pages" +.SH NAME +Num.round \- Rounds a number to the nearest whole number integer. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.round : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Rounds a number to the nearest whole number integer. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number to be rounded. - +.TE +.SH RETURN +The nearest integer value of `x`. + +.SH EXAMPLES +.EX +>> (2.3).round() += 2 +>> (2.7).round() += 3 +.EE diff --git a/man/man3/tomo-Num.scientific.3 b/man/man3/tomo-Num.scientific.3 new file mode 100644 index 00000000..e1db35a1 --- /dev/null +++ b/man/man3/tomo-Num.scientific.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.scientific 3 2025-04-19T14:30:40.363662 "Tomo man-pages" +.SH NAME +Num.scientific \- Formats a number in scientific notation with a specified precision. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.scientific : func(n: Num, precision: Int = 0 -> Text)" +.fi + +.SH DESCRIPTION +Formats a number in scientific notation with a specified precision. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +n Num The number to be formatted. - +precision Int The number of decimal places. Default is `0`. 0 +.TE +.SH RETURN +A text representation of the number in scientific notation with the specified precision. + +.SH EXAMPLES +.EX +>> (12345.6789).scientific(precision=2) += "1.23e+04" +.EE diff --git a/man/man3/tomo-Num.significand.3 b/man/man3/tomo-Num.significand.3 new file mode 100644 index 00000000..44f20d64 --- /dev/null +++ b/man/man3/tomo-Num.significand.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.significand 3 2025-04-19T14:30:40.363710 "Tomo man-pages" +.SH NAME +Num.significand \- Extracts the significand (or mantissa) of a number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.significand : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Extracts the significand (or mantissa) of a number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number from which to extract the significand. - +.TE +.SH RETURN +The significand of `x`. + +.SH EXAMPLES +.EX +>> (1234.567).significand() += 0.1234567 +.EE diff --git a/man/man3/tomo-Num.sin.3 b/man/man3/tomo-Num.sin.3 new file mode 100644 index 00000000..3781cdc4 --- /dev/null +++ b/man/man3/tomo-Num.sin.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.sin 3 2025-04-19T14:30:40.363772 "Tomo man-pages" +.SH NAME +Num.sin \- Computes the sine of a number (angle in radians). + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.sin : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the sine of a number (angle in radians). + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The angle in radians. - +.TE +.SH RETURN +The sine of `x`. + +.SH EXAMPLES +.EX +>> (0.0).sin() += 0 +.EE diff --git a/man/man3/tomo-Num.sinh.3 b/man/man3/tomo-Num.sinh.3 new file mode 100644 index 00000000..00cf9442 --- /dev/null +++ b/man/man3/tomo-Num.sinh.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.sinh 3 2025-04-19T14:30:40.363864 "Tomo man-pages" +.SH NAME +Num.sinh \- Computes the hyperbolic sine of a number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.sinh : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the hyperbolic sine of a number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number for which the hyperbolic sine is to be calculated. - +.TE +.SH RETURN +The hyperbolic sine of `x`. + +.SH EXAMPLES +.EX +>> (0.0).sinh() += 0 +.EE diff --git a/man/man3/tomo-Num.sqrt.3 b/man/man3/tomo-Num.sqrt.3 new file mode 100644 index 00000000..f6feb3b6 --- /dev/null +++ b/man/man3/tomo-Num.sqrt.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.sqrt 3 2025-04-19T14:30:40.363914 "Tomo man-pages" +.SH NAME +Num.sqrt \- Computes the square root of a number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.sqrt : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the square root of a number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number for which the square root is to be calculated. - +.TE +.SH RETURN +The square root of `x`. + +.SH EXAMPLES +.EX +>> (16.0).sqrt() += 4 +.EE diff --git a/man/man3/tomo-Num.tan.3 b/man/man3/tomo-Num.tan.3 new file mode 100644 index 00000000..079f6929 --- /dev/null +++ b/man/man3/tomo-Num.tan.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.tan 3 2025-04-19T14:30:40.363954 "Tomo man-pages" +.SH NAME +Num.tan \- Computes the tangent of a number (angle in radians). + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.tan : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the tangent of a number (angle in radians). + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The angle in radians. - +.TE +.SH RETURN +The tangent of `x`. + +.SH EXAMPLES +.EX +>> (0.0).tan() += 0 +.EE diff --git a/man/man3/tomo-Num.tanh.3 b/man/man3/tomo-Num.tanh.3 new file mode 100644 index 00000000..91c3307a --- /dev/null +++ b/man/man3/tomo-Num.tanh.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.tanh 3 2025-04-19T14:30:40.364021 "Tomo man-pages" +.SH NAME +Num.tanh \- Computes the hyperbolic tangent of a number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.tanh : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the hyperbolic tangent of a number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number for which the hyperbolic tangent is to be calculated. - +.TE +.SH RETURN +The hyperbolic tangent of `x`. + +.SH EXAMPLES +.EX +>> (0.0).tanh() += 0 +.EE diff --git a/man/man3/tomo-Num.tgamma.3 b/man/man3/tomo-Num.tgamma.3 new file mode 100644 index 00000000..2ad83495 --- /dev/null +++ b/man/man3/tomo-Num.tgamma.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.tgamma 3 2025-04-19T14:30:40.364064 "Tomo man-pages" +.SH NAME +Num.tgamma \- Computes the gamma function of a number. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.tgamma : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the gamma function of a number. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number for which the gamma function is to be calculated. - +.TE +.SH RETURN +The gamma function of `x`. + +.SH EXAMPLES +.EX +>> (1.0).tgamma() += 1 +.EE diff --git a/man/man3/tomo-Num.trunc.3 b/man/man3/tomo-Num.trunc.3 new file mode 100644 index 00000000..9c72b39c --- /dev/null +++ b/man/man3/tomo-Num.trunc.3 @@ -0,0 +1,36 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.trunc 3 2025-04-19T14:30:40.364102 "Tomo man-pages" +.SH NAME +Num.trunc \- Truncates a number to the nearest integer towards zero. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.trunc : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Truncates a number to the nearest integer towards zero. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number to be truncated. - +.TE +.SH RETURN +The integer part of `x` towards zero. + +.SH EXAMPLES +.EX +>> (3.7).trunc() += 3 +>> (-3.7).trunc() += -3 +.EE diff --git a/man/man3/tomo-Num.y0.3 b/man/man3/tomo-Num.y0.3 new file mode 100644 index 00000000..593924e4 --- /dev/null +++ b/man/man3/tomo-Num.y0.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.y0 3 2025-04-19T14:30:40.364161 "Tomo man-pages" +.SH NAME +Num.y0 \- Computes the Bessel function of the second kind of order 0. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.y0 : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the Bessel function of the second kind of order 0. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number for which the Bessel function is to be calculated. - +.TE +.SH RETURN +The Bessel function of the second kind of order 0 of `x`. + +.SH EXAMPLES +.EX +>> (1.0).y0() += -0.7652 +.EE diff --git a/man/man3/tomo-Num.y1.3 b/man/man3/tomo-Num.y1.3 new file mode 100644 index 00000000..eadb9dc9 --- /dev/null +++ b/man/man3/tomo-Num.y1.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Num.y1 3 2025-04-19T14:30:40.364215 "Tomo man-pages" +.SH NAME +Num.y1 \- Computes the Bessel function of the second kind of order 1. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Num.y1 : func(x: Num -> Num)" +.fi + +.SH DESCRIPTION +Computes the Bessel function of the second kind of order 1. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +x Num The number for which the Bessel function is to be calculated. - +.TE +.SH RETURN +The Bessel function of the second kind of order 1 of `x`. + +.SH EXAMPLES +.EX +>> (1.0).y1() += 0.4401 +.EE diff --git a/man/man3/tomo-Path.accessed.3 b/man/man3/tomo-Path.accessed.3 new file mode 100644 index 00000000..eba79006 --- /dev/null +++ b/man/man3/tomo-Path.accessed.3 @@ -0,0 +1,37 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.accessed 3 2025-04-19T14:30:40.364725 "Tomo man-pages" +.SH NAME +Path.accessed \- Gets the file access time of a file. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.accessed : func(path: Path, follow_symlinks: Bool = yes -> Int64?)" +.fi + +.SH DESCRIPTION +Gets the file access time of a file. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path of the file whose access time you want. - +follow_symlinks Bool Whether to follow symbolic links. yes +.TE +.SH RETURN +A 64-bit unix epoch timestamp representing when the file or directory was last accessed, or `none` if no such file or directory exists. + +.SH EXAMPLES +.EX +>> (./file.txt).accessed() += 1704221100? +>> (./not-a-file).accessed() += none +.EE diff --git a/man/man3/tomo-Path.append.3 b/man/man3/tomo-Path.append.3 new file mode 100644 index 00000000..c008cb66 --- /dev/null +++ b/man/man3/tomo-Path.append.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.append 3 2025-04-19T14:30:40.364773 "Tomo man-pages" +.SH NAME +Path.append \- Appends the given text to the file at the specified path, creating the file if it doesn't already exist. Failure to write will result in a runtime error. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.append : func(path: Path, text: Text, permissions: Int32 = Int32(0o644) -> Void)" +.fi + +.SH DESCRIPTION +Appends the given text to the file at the specified path, creating the file if it doesn't already exist. Failure to write will result in a runtime error. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path of the file to append to. - +text Text The text to append to the file. - +permissions Int32 The permissions to set on the file if it is being created. Int32(0o644) +.TE +.SH RETURN +Nothing. + +.SH EXAMPLES +.EX +(./log.txt).append("extra line$(\\n)") +.EE diff --git a/man/man3/tomo-Path.append_bytes.3 b/man/man3/tomo-Path.append_bytes.3 new file mode 100644 index 00000000..01bda089 --- /dev/null +++ b/man/man3/tomo-Path.append_bytes.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.append_bytes 3 2025-04-19T14:30:40.364816 "Tomo man-pages" +.SH NAME +Path.append_bytes \- Appends the given bytes to the file at the specified path, creating the file if it doesn't already exist. Failure to write will result in a runtime error. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.append_bytes : func(path: Path, bytes: [Byte], permissions: Int32 = Int32(0o644) -> Void)" +.fi + +.SH DESCRIPTION +Appends the given bytes to the file at the specified path, creating the file if it doesn't already exist. Failure to write will result in a runtime error. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path of the file to append to. - +bytes [Byte] The bytes to append to the file. - +permissions Int32 The permissions to set on the file if it is being created. Int32(0o644) +.TE +.SH RETURN +Nothing. + +.SH EXAMPLES +.EX +(./log.txt).append_bytes([104, 105]) +.EE diff --git a/man/man3/tomo-Path.base_name.3 b/man/man3/tomo-Path.base_name.3 new file mode 100644 index 00000000..3838ead2 --- /dev/null +++ b/man/man3/tomo-Path.base_name.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.base_name 3 2025-04-19T14:30:40.364857 "Tomo man-pages" +.SH NAME +Path.base_name \- Returns the base name of the file or directory at the specified path. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.base_name : func(path: Path -> Text)" +.fi + +.SH DESCRIPTION +Returns the base name of the file or directory at the specified path. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path of the file or directory. - +.TE +.SH RETURN +The base name of the file or directory. + +.SH EXAMPLES +.EX +>> (./path/to/file.txt).base_name() += "file.txt" +.EE diff --git a/man/man3/tomo-Path.by_line.3 b/man/man3/tomo-Path.by_line.3 new file mode 100644 index 00000000..2770833c --- /dev/null +++ b/man/man3/tomo-Path.by_line.3 @@ -0,0 +1,42 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.by_line 3 2025-04-19T14:30:40.364894 "Tomo man-pages" +.SH NAME +Path.by_line \- Returns an iterator that can be used to iterate over a file one line at a time, or returns a null value if the file could not be opened. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.by_line : func(path: Path -> func(->Text?)?)" +.fi + +.SH DESCRIPTION +Returns an iterator that can be used to iterate over a file one line at a time, or returns a null value if the file could not be opened. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path of the file. - +.TE +.SH RETURN +An iterator that can be used to get lines from a file one at a time or a null value if the file couldn't be read. + +.SH EXAMPLES +.EX +# Safely handle file not being readable: +if lines := (./file.txt).by_line() +for line in lines +say(line.upper()) +else +say("Couldn't read file!") + +# Assume the file is readable and error if that's not the case: +for line in (/dev/stdin).by_line()! +say(line.upper()) +.EE diff --git a/man/man3/tomo-Path.can_execute.3 b/man/man3/tomo-Path.can_execute.3 new file mode 100644 index 00000000..eb0a0cb6 --- /dev/null +++ b/man/man3/tomo-Path.can_execute.3 @@ -0,0 +1,38 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.can_execute 3 2025-04-19T14:30:40.364935 "Tomo man-pages" +.SH NAME +Path.can_execute \- Returns whether or not a file can be executed by the current user/group. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.can_execute : func(path: Path -> Bool)" +.fi + +.SH DESCRIPTION +Returns whether or not a file can be executed by the current user/group. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path of the file to check. - +.TE +.SH RETURN +`yes` if the file or directory exists and the current user has execute permissions, otherwise `no`. + +.SH EXAMPLES +.EX +>> (/bin/sh).can_execute() += yes +>> (/usr/include/stdlib.h).can_execute() += no +>> (/non/existant/file).can_execute() += no +.EE diff --git a/man/man3/tomo-Path.can_read.3 b/man/man3/tomo-Path.can_read.3 new file mode 100644 index 00000000..f54f9362 --- /dev/null +++ b/man/man3/tomo-Path.can_read.3 @@ -0,0 +1,38 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.can_read 3 2025-04-19T14:30:40.364972 "Tomo man-pages" +.SH NAME +Path.can_read \- Returns whether or not a file can be read by the current user/group. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.can_read : func(path: Path -> Bool)" +.fi + +.SH DESCRIPTION +Returns whether or not a file can be read by the current user/group. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path of the file to check. - +.TE +.SH RETURN +`yes` if the file or directory exists and the current user has read permissions, otherwise `no`. + +.SH EXAMPLES +.EX +>> (/usr/include/stdlib.h).can_read() += yes +>> (/etc/shadow).can_read() += no +>> (/non/existant/file).can_read() += no +.EE diff --git a/man/man3/tomo-Path.can_write.3 b/man/man3/tomo-Path.can_write.3 new file mode 100644 index 00000000..af27a504 --- /dev/null +++ b/man/man3/tomo-Path.can_write.3 @@ -0,0 +1,38 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.can_write 3 2025-04-19T14:30:40.365009 "Tomo man-pages" +.SH NAME +Path.can_write \- Returns whether or not a file can be written by the current user/group. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.can_write : func(path: Path -> Bool)" +.fi + +.SH DESCRIPTION +Returns whether or not a file can be written by the current user/group. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path of the file to check. - +.TE +.SH RETURN +`yes` if the file or directory exists and the current user has write permissions, otherwise `no`. + +.SH EXAMPLES +.EX +>> (/tmp).can_write() += yes +>> (/etc/passwd).can_write() += no +>> (/non/existant/file).can_write() += no +.EE diff --git a/man/man3/tomo-Path.changed.3 b/man/man3/tomo-Path.changed.3 new file mode 100644 index 00000000..56d8fd97 --- /dev/null +++ b/man/man3/tomo-Path.changed.3 @@ -0,0 +1,40 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.changed 3 2025-04-19T14:30:40.365046 "Tomo man-pages" +.SH NAME +Path.changed \- Gets the file change time of a file. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.changed : func(path: Path, follow_symlinks: Bool = yes -> Int64?)" +.fi + +.SH DESCRIPTION +Gets the file change time of a file. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path of the file whose change time you want. - +follow_symlinks Bool Whether to follow symbolic links. yes +.TE +.SH RETURN +A 64-bit unix epoch timestamp representing when the file or directory was last changed, or `none` if no such file or directory exists. + +.SH NOTES +This is the ["ctime"](https://en.wikipedia.org/wiki/Stat_(system_call)#ctime) of a file, which is _not_ the file creation time. + +.SH EXAMPLES +.EX +>> (./file.txt).changed() += 1704221100? +>> (./not-a-file).changed() += none +.EE diff --git a/man/man3/tomo-Path.child.3 b/man/man3/tomo-Path.child.3 new file mode 100644 index 00000000..7ae2799a --- /dev/null +++ b/man/man3/tomo-Path.child.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.child 3 2025-04-19T14:30:40.365083 "Tomo man-pages" +.SH NAME +Path.child \- Return a path that is a child of another path. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.child : func(path: Path, child: Text -> [Path])" +.fi + +.SH DESCRIPTION +Return a path that is a child of another path. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path of a directory. - +child Text The name of a child file or directory. - +.TE +.SH RETURN +A new path representing the child. + +.SH EXAMPLES +.EX +>> (./directory).child("file.txt") += (./directory/file.txt) +.EE diff --git a/man/man3/tomo-Path.children.3 b/man/man3/tomo-Path.children.3 new file mode 100644 index 00000000..acbc92ff --- /dev/null +++ b/man/man3/tomo-Path.children.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.children 3 2025-04-19T14:30:40.365120 "Tomo man-pages" +.SH NAME +Path.children \- Returns a list of children (files and directories) within the directory at the specified path. Optionally includes hidden files. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.children : func(path: Path, include_hidden = no -> [Path])" +.fi + +.SH DESCRIPTION +Returns a list of children (files and directories) within the directory at the specified path. Optionally includes hidden files. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path of the directory. - +include_hidden Whether to include hidden files, which start with a `.`. no +.TE +.SH RETURN +A list of paths for the children. + +.SH EXAMPLES +.EX +>> (./directory).children(include_hidden=yes) += [".git", "foo.txt"] +.EE diff --git a/man/man3/tomo-Path.create_directory.3 b/man/man3/tomo-Path.create_directory.3 new file mode 100644 index 00000000..ef498a1a --- /dev/null +++ b/man/man3/tomo-Path.create_directory.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.create_directory 3 2025-04-19T14:30:40.365156 "Tomo man-pages" +.SH NAME +Path.create_directory \- Creates a new directory at the specified path with the given permissions. If any of the parent directories do not exist, they will be created as needed. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.create_directory : func(path: Path, permissions = Int32(0o755) -> Void)" +.fi + +.SH DESCRIPTION +Creates a new directory at the specified path with the given permissions. If any of the parent directories do not exist, they will be created as needed. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path of the directory to create. - +permissions The permissions to set on the new directory. Int32(0o755) +.TE +.SH RETURN +Nothing. + +.SH EXAMPLES +.EX +(./new_directory).create_directory() +.EE diff --git a/man/man3/tomo-Path.current_dir.3 b/man/man3/tomo-Path.current_dir.3 new file mode 100644 index 00000000..5838aa64 --- /dev/null +++ b/man/man3/tomo-Path.current_dir.3 @@ -0,0 +1,26 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.current_dir 3 2025-04-19T14:30:40.365191 "Tomo man-pages" +.SH NAME +Path.current_dir \- Creates a new directory at the specified path with the given permissions. If any of the parent directories do not exist, they will be created as needed. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.current_dir : func(-> Path)" +.fi + +.SH DESCRIPTION +Creates a new directory at the specified path with the given permissions. If any of the parent directories do not exist, they will be created as needed. + +.SH RETURN +The absolute path of the current directory. + +.SH EXAMPLES +.EX +>> Path.current_dir() += (/home/user/tomo) +.EE diff --git a/man/man3/tomo-Path.exists.3 b/man/man3/tomo-Path.exists.3 new file mode 100644 index 00000000..ea01f95b --- /dev/null +++ b/man/man3/tomo-Path.exists.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.exists 3 2025-04-19T14:30:40.365224 "Tomo man-pages" +.SH NAME +Path.exists \- Checks if a file or directory exists at the specified path. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.exists : func(path: Path -> Bool)" +.fi + +.SH DESCRIPTION +Checks if a file or directory exists at the specified path. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path to check. - +.TE +.SH RETURN +`True` if the file or directory exists, `False` otherwise. + +.SH EXAMPLES +.EX +>> (/).exists() += yes +.EE diff --git a/man/man3/tomo-Path.expand_home.3 b/man/man3/tomo-Path.expand_home.3 new file mode 100644 index 00000000..389bee30 --- /dev/null +++ b/man/man3/tomo-Path.expand_home.3 @@ -0,0 +1,36 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.expand_home 3 2025-04-19T14:30:40.365279 "Tomo man-pages" +.SH NAME +Path.expand_home \- For home-based paths (those starting with `~`), expand the path to replace the tilde with and absolute path to the user's `$HOME` directory. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.expand_home : func(path: Path -> Path)" +.fi + +.SH DESCRIPTION +For home-based paths (those starting with `~`), expand the path to replace the tilde with and absolute path to the user's `$HOME` directory. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path to expand. - +.TE +.SH RETURN +If the path does not start with a `~`, then return it unmodified. Otherwise, replace the `~` with an absolute path to the user's home directory. + +.SH EXAMPLES +.EX +>> (~/foo).expand_home() # Assume current user is 'user' += /home/user/foo +>> (/foo).expand_home() # No change += /foo +.EE diff --git a/man/man3/tomo-Path.extension.3 b/man/man3/tomo-Path.extension.3 new file mode 100644 index 00000000..3fb13fc7 --- /dev/null +++ b/man/man3/tomo-Path.extension.3 @@ -0,0 +1,41 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.extension 3 2025-04-19T14:30:40.365321 "Tomo man-pages" +.SH NAME +Path.extension \- Returns the file extension of the file at the specified path. Optionally returns the full extension. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.extension : func(path: Path, full: Bool = yes -> Text)" +.fi + +.SH DESCRIPTION +Returns the file extension of the file at the specified path. Optionally returns the full extension. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path of the file. - +full Bool Whether to return everything after the first `.` in the base name, or only the last part of the extension. yes +.TE +.SH RETURN +The file extension (not including the leading `.`) or an empty text if there is no file extension. + +.SH EXAMPLES +.EX +>> (./file.tar.gz).extension() += "tar.gz" +>> (./file.tar.gz).extension(full=no) += "gz" +>> (/foo).extension() += "" +>> (./.git).extension() += "" +.EE diff --git a/man/man3/tomo-Path.files.3 b/man/man3/tomo-Path.files.3 new file mode 100644 index 00000000..e1df767b --- /dev/null +++ b/man/man3/tomo-Path.files.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.files 3 2025-04-19T14:30:40.365361 "Tomo man-pages" +.SH NAME +Path.files \- Returns a list of files within the directory at the specified path. Optionally includes hidden files. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.files : func(path: Path, include_hidden: Bool = no -> [Path])" +.fi + +.SH DESCRIPTION +Returns a list of files within the directory at the specified path. Optionally includes hidden files. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path of the directory. - +include_hidden Bool Whether to include hidden files. no +.TE +.SH RETURN +A list of file paths. + +.SH EXAMPLES +.EX +>> (./directory).files(include_hidden=yes) += [(./directory/file1.txt), (./directory/file2.txt)] +.EE diff --git a/man/man3/tomo-Path.from_components.3 b/man/man3/tomo-Path.from_components.3 new file mode 100644 index 00000000..cb5879c1 --- /dev/null +++ b/man/man3/tomo-Path.from_components.3 @@ -0,0 +1,38 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.from_components 3 2025-04-19T14:30:40.365399 "Tomo man-pages" +.SH NAME +Path.from_components \- Returns a path built from a list of path components. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.from_components : func(components: [Text] -> Path)" +.fi + +.SH DESCRIPTION +Returns a path built from a list of path components. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +components [Text] A list of path components. - +.TE +.SH RETURN +A path representing the given components. + +.SH EXAMPLES +.EX +>> Path.from_components(["/", "usr", "include"]) += /usr/include +>> Path.from_components(["foo.txt"]) += ./foo.txt +>> Path.from_components(["~", ".local"]) += ~/.local +.EE diff --git a/man/man3/tomo-Path.glob.3 b/man/man3/tomo-Path.glob.3 new file mode 100644 index 00000000..8d48171e --- /dev/null +++ b/man/man3/tomo-Path.glob.3 @@ -0,0 +1,60 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.glob 3 2025-04-19T14:30:40.365437 "Tomo man-pages" +.SH NAME +Path.glob \- Perform a globbing operation and return a list of matching paths. Some glob specific details: +- The paths "." and ".." are *not* included in any globbing results. +- Files or directories that begin with "." will not match `*`, but will match `.*`. +- Globs do support `{a,b}` syntax for matching files that match any of several + choices of patterns. + +- The shell-style syntax `**` for matching subdirectories is not supported. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.glob : func(path: Path -> [Path])" +.fi + +.SH DESCRIPTION +Perform a globbing operation and return a list of matching paths. Some glob specific details: +- The paths "." and ".." are *not* included in any globbing results. +- Files or directories that begin with "." will not match `*`, but will match `.*`. +- Globs do support `{a,b}` syntax for matching files that match any of several + choices of patterns. + +- The shell-style syntax `**` for matching subdirectories is not supported. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path of the directory which may contain special globbing characters like `*`, `?`, or `{...}` - +.TE +.SH RETURN +A list of file paths that match the glob. + +.SH EXAMPLES +.EX +# Current directory includes: foo.txt, baz.txt, qux.jpg, .hidden +>> (./*).glob() += [(./foo.txt), (./baz.txt), (./qux.jpg)] + +>> (./*.txt).glob() += [(./foo.txt), (./baz.txt)] + +>> (./*.{txt,jpg}).glob() += [(./foo.txt), (./baz.txt), (./qux.jpg)] + +>> (./.*).glob() += [(./.hidden)] + +# Globs with no matches return an empty list: +>> (./*.xxx).glob() += [] +.EE diff --git a/man/man3/tomo-Path.group.3 b/man/man3/tomo-Path.group.3 new file mode 100644 index 00000000..615f5777 --- /dev/null +++ b/man/man3/tomo-Path.group.3 @@ -0,0 +1,37 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.group 3 2025-04-19T14:30:40.365486 "Tomo man-pages" +.SH NAME +Path.group \- Get the owning group of a file or directory. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.group : func(path: Path, follow_symlinks: Bool = yes -> Text?)" +.fi + +.SH DESCRIPTION +Get the owning group of a file or directory. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path whose owning group to get. - +follow_symlinks Bool Whether to follow symbolic links. yes +.TE +.SH RETURN +The name of the group which owns the file or directory, or `none` if the path does not exist. + +.SH EXAMPLES +.EX +>> (/bin).group() += "root" +>> (/non/existent/file).group() += none +.EE diff --git a/man/man3/tomo-Path.is_directory.3 b/man/man3/tomo-Path.is_directory.3 new file mode 100644 index 00000000..89953dcc --- /dev/null +++ b/man/man3/tomo-Path.is_directory.3 @@ -0,0 +1,38 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.is_directory 3 2025-04-19T14:30:40.365526 "Tomo man-pages" +.SH NAME +Path.is_directory \- Checks if the path represents a directory. Optionally follows symbolic links. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.is_directory : func(path: Path, follow_symlinks = yes -> Bool)" +.fi + +.SH DESCRIPTION +Checks if the path represents a directory. Optionally follows symbolic links. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path to check. - +follow_symlinks Whether to follow symbolic links. yes +.TE +.SH RETURN +`True` if the path is a directory, `False` otherwise. + +.SH EXAMPLES +.EX +>> (./directory/).is_directory() += yes + +>> (./file.txt).is_directory() += no +.EE diff --git a/man/man3/tomo-Path.is_file.3 b/man/man3/tomo-Path.is_file.3 new file mode 100644 index 00000000..9bb6fb56 --- /dev/null +++ b/man/man3/tomo-Path.is_file.3 @@ -0,0 +1,38 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.is_file 3 2025-04-19T14:30:40.365567 "Tomo man-pages" +.SH NAME +Path.is_file \- Checks if the path represents a file. Optionally follows symbolic links. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.is_file : func(path: Path, follow_symlinks = yes -> Bool)" +.fi + +.SH DESCRIPTION +Checks if the path represents a file. Optionally follows symbolic links. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path to check. - +follow_symlinks Whether to follow symbolic links. yes +.TE +.SH RETURN +`True` if the path is a file, `False` otherwise. + +.SH EXAMPLES +.EX +>> (./file.txt).is_file() += yes + +>> (./directory/).is_file() += no +.EE diff --git a/man/man3/tomo-Path.is_socket.3 b/man/man3/tomo-Path.is_socket.3 new file mode 100644 index 00000000..b7465f78 --- /dev/null +++ b/man/man3/tomo-Path.is_socket.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.is_socket 3 2025-04-19T14:30:40.365604 "Tomo man-pages" +.SH NAME +Path.is_socket \- Checks if the path represents a socket. Optionally follows symbolic links. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.is_socket : func(path: Path, follow_symlinks = yes -> Bool)" +.fi + +.SH DESCRIPTION +Checks if the path represents a socket. Optionally follows symbolic links. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path to check. - +follow_symlinks Whether to follow symbolic links. yes +.TE +.SH RETURN +`True` if the path is a socket, `False` otherwise. + +.SH EXAMPLES +.EX +>> (./socket).is_socket() += yes +.EE diff --git a/man/man3/tomo-Path.is_symlink.3 b/man/man3/tomo-Path.is_symlink.3 new file mode 100644 index 00000000..d1a743bb --- /dev/null +++ b/man/man3/tomo-Path.is_symlink.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.is_symlink 3 2025-04-19T14:30:40.365640 "Tomo man-pages" +.SH NAME +Path.is_symlink \- Checks if the path represents a symbolic link. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.is_symlink : func(path: Path -> Bool)" +.fi + +.SH DESCRIPTION +Checks if the path represents a symbolic link. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path to check. - +.TE +.SH RETURN +`True` if the path is a symbolic link, `False` otherwise. + +.SH EXAMPLES +.EX +>> (./link).is_symlink() += yes +.EE diff --git a/man/man3/tomo-Path.modified.3 b/man/man3/tomo-Path.modified.3 new file mode 100644 index 00000000..f7c5f48d --- /dev/null +++ b/man/man3/tomo-Path.modified.3 @@ -0,0 +1,37 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.modified 3 2025-04-19T14:30:40.365676 "Tomo man-pages" +.SH NAME +Path.modified \- Gets the file modification time of a file. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.modified : func(path: Path, follow_symlinks: Bool = yes -> Int64?)" +.fi + +.SH DESCRIPTION +Gets the file modification time of a file. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path of the file whose modification time you want. - +follow_symlinks Bool Whether to follow symbolic links. yes +.TE +.SH RETURN +A 64-bit unix epoch timestamp representing when the file or directory was last modified, or `none` if no such file or directory exists. + +.SH EXAMPLES +.EX +>> (./file.txt).modified() += 1704221100? +>> (./not-a-file).modified() += none +.EE diff --git a/man/man3/tomo-Path.owner.3 b/man/man3/tomo-Path.owner.3 new file mode 100644 index 00000000..65d66404 --- /dev/null +++ b/man/man3/tomo-Path.owner.3 @@ -0,0 +1,37 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.owner 3 2025-04-19T14:30:40.365713 "Tomo man-pages" +.SH NAME +Path.owner \- Get the owning user of a file or directory. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.owner : func(path: Path, follow_symlinks: Bool = yes -> Text?)" +.fi + +.SH DESCRIPTION +Get the owning user of a file or directory. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path whose owner to get. - +follow_symlinks Bool Whether to follow symbolic links. yes +.TE +.SH RETURN +The name of the user who owns the file or directory, or `none` if the path does not exist. + +.SH EXAMPLES +.EX +>> (/bin).owner() += "root" +>> (/non/existent/file).owner() += none +.EE diff --git a/man/man3/tomo-Path.parent.3 b/man/man3/tomo-Path.parent.3 new file mode 100644 index 00000000..36d33058 --- /dev/null +++ b/man/man3/tomo-Path.parent.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.parent 3 2025-04-19T14:30:40.365748 "Tomo man-pages" +.SH NAME +Path.parent \- Returns the parent directory of the file or directory at the specified path. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.parent : func(path: Path -> Path)" +.fi + +.SH DESCRIPTION +Returns the parent directory of the file or directory at the specified path. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path of the file or directory. - +.TE +.SH RETURN +The path of the parent directory. + +.SH EXAMPLES +.EX +>> (./path/to/file.txt).parent() += (./path/to/) +.EE diff --git a/man/man3/tomo-Path.read.3 b/man/man3/tomo-Path.read.3 new file mode 100644 index 00000000..13630d96 --- /dev/null +++ b/man/man3/tomo-Path.read.3 @@ -0,0 +1,37 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.read 3 2025-04-19T14:30:40.365795 "Tomo man-pages" +.SH NAME +Path.read \- Reads the contents of the file at the specified path or a null value if the file could not be read. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.read : func(path: Path -> Text?)" +.fi + +.SH DESCRIPTION +Reads the contents of the file at the specified path or a null value if the file could not be read. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path of the file to read. - +.TE +.SH RETURN +The contents of the file. If the file could not be read, a null value will be returned. If the file can be read, but is not valid UTF8 data, an error will be raised. + +.SH EXAMPLES +.EX +>> (./hello.txt).read() += "Hello"? + +>> (./nosuchfile.xxx).read() += none +.EE diff --git a/man/man3/tomo-Path.read_bytes.3 b/man/man3/tomo-Path.read_bytes.3 new file mode 100644 index 00000000..b1be93e9 --- /dev/null +++ b/man/man3/tomo-Path.read_bytes.3 @@ -0,0 +1,38 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.read_bytes 3 2025-04-19T14:30:40.365850 "Tomo man-pages" +.SH NAME +Path.read_bytes \- Reads the contents of the file at the specified path or a null value if the file could not be read. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.read_bytes : func(path: Path, limit: Int? = none -> [Byte]?)" +.fi + +.SH DESCRIPTION +Reads the contents of the file at the specified path or a null value if the file could not be read. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path of the file to read. - +limit Int? A limit to how many bytes should be read. none +.TE +.SH RETURN +The byte contents of the file. If the file cannot be read, a null value will be returned. + +.SH EXAMPLES +.EX +>> (./hello.txt).read() += [72, 101, 108, 108, 111]? + +>> (./nosuchfile.xxx).read() += none +.EE diff --git a/man/man3/tomo-Path.relative_to.3 b/man/man3/tomo-Path.relative_to.3 new file mode 100644 index 00000000..b2ee1ce3 --- /dev/null +++ b/man/man3/tomo-Path.relative_to.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.relative_to 3 2025-04-19T14:30:40.365893 "Tomo man-pages" +.SH NAME +Path.relative_to \- Returns the path relative to a given base path. By default, the base path is the current directory. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.relative_to : func(path: Path, relative_to = (./) -> Path)" +.fi + +.SH DESCRIPTION +Returns the path relative to a given base path. By default, the base path is the current directory. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path to convert. - +relative_to The base path for the relative path. (./) +.TE +.SH RETURN +The relative path. + +.SH EXAMPLES +.EX +>> (./path/to/file.txt).relative(relative_to=(./path)) += (./to/file.txt) +.EE diff --git a/man/man3/tomo-Path.remove.3 b/man/man3/tomo-Path.remove.3 new file mode 100644 index 00000000..252e9665 --- /dev/null +++ b/man/man3/tomo-Path.remove.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.remove 3 2025-04-19T14:30:40.365933 "Tomo man-pages" +.SH NAME +Path.remove \- Removes the file or directory at the specified path. A runtime error is raised if something goes wrong. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.remove : func(path: Path, ignore_missing = no -> Void)" +.fi + +.SH DESCRIPTION +Removes the file or directory at the specified path. A runtime error is raised if something goes wrong. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path to remove. - +ignore_missing Whether to ignore errors if the file or directory does not exist. no +.TE +.SH RETURN +Nothing. + +.SH EXAMPLES +.EX +(./file.txt).remove() +.EE diff --git a/man/man3/tomo-Path.resolved.3 b/man/man3/tomo-Path.resolved.3 new file mode 100644 index 00000000..afc67b8a --- /dev/null +++ b/man/man3/tomo-Path.resolved.3 @@ -0,0 +1,38 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.resolved 3 2025-04-19T14:30:40.365971 "Tomo man-pages" +.SH NAME +Path.resolved \- Resolves the absolute path of the given path relative to a base path. By default, the base path is the current directory. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.resolved : func(path: Path, relative_to = (./) -> Path)" +.fi + +.SH DESCRIPTION +Resolves the absolute path of the given path relative to a base path. By default, the base path is the current directory. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path to resolve. - +relative_to The base path for resolution. (./) +.TE +.SH RETURN +The resolved absolute path. + +.SH EXAMPLES +.EX +>> (~/foo).resolved() += (/home/user/foo) + +>> (./path/to/file.txt).resolved(relative_to=(/foo)) += (/foo/path/to/file.txt) +.EE diff --git a/man/man3/tomo-Path.set_owner.3 b/man/man3/tomo-Path.set_owner.3 new file mode 100644 index 00000000..24e8f697 --- /dev/null +++ b/man/man3/tomo-Path.set_owner.3 @@ -0,0 +1,36 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.set_owner 3 2025-04-19T14:30:40.366011 "Tomo man-pages" +.SH NAME +Path.set_owner \- Set the owning user and/or group for a path. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.set_owner : func(path: Path, owner: Text? = none, group: Text? = none, follow_symlinks: Bool = yes -> Void)" +.fi + +.SH DESCRIPTION +Set the owning user and/or group for a path. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path to change the permissions for. - +owner Text? If non-none, the new user to assign to be the owner of the file. none +group Text? If non-none, the new group to assign to be the owner of the file. none +follow_symlinks Bool Whether to follow symbolic links. yes +.TE +.SH RETURN +Nothing. If a path does not exist, a failure will be raised. + +.SH EXAMPLES +.EX +(./file.txt).set_owner(owner="root", group="wheel") +.EE diff --git a/man/man3/tomo-Path.subdirectories.3 b/man/man3/tomo-Path.subdirectories.3 new file mode 100644 index 00000000..16c68be4 --- /dev/null +++ b/man/man3/tomo-Path.subdirectories.3 @@ -0,0 +1,38 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.subdirectories 3 2025-04-19T14:30:40.366051 "Tomo man-pages" +.SH NAME +Path.subdirectories \- Returns a list of subdirectories within the directory at the specified path. Optionally includes hidden subdirectories. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.subdirectories : func(path: Path, include_hidden = no -> [Path])" +.fi + +.SH DESCRIPTION +Returns a list of subdirectories within the directory at the specified path. Optionally includes hidden subdirectories. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path of the directory. - +include_hidden Whether to include hidden subdirectories. no +.TE +.SH RETURN +A list of subdirectory paths. + +.SH EXAMPLES +.EX +>> (./directory).subdirectories() += [(./directory/subdir1), (./directory/subdir2)] + +>> (./directory).subdirectories(include_hidden=yes) += [(./directory/.git), (./directory/subdir1), (./directory/subdir2)] +.EE diff --git a/man/man3/tomo-Path.unique_directory.3 b/man/man3/tomo-Path.unique_directory.3 new file mode 100644 index 00000000..b7e4cfb8 --- /dev/null +++ b/man/man3/tomo-Path.unique_directory.3 @@ -0,0 +1,37 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.unique_directory 3 2025-04-19T14:30:40.366088 "Tomo man-pages" +.SH NAME +Path.unique_directory \- Generates a unique directory path based on the given path. Useful for creating temporary directories. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.unique_directory : func(path: Path -> Path)" +.fi + +.SH DESCRIPTION +Generates a unique directory path based on the given path. Useful for creating temporary directories. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The base path for generating the unique directory. The last six letters of this path must be `XXXXXX`. - +.TE +.SH RETURN +A unique directory path after creating the directory. + +.SH EXAMPLES +.EX +>> created := (/tmp/my-dir.XXXXXX).unique_directory() += (/tmp/my-dir-AwoxbM/) +>> created.is_directory() += yes +created.remove() +.EE diff --git a/man/man3/tomo-Path.write.3 b/man/man3/tomo-Path.write.3 new file mode 100644 index 00000000..7dd28ab0 --- /dev/null +++ b/man/man3/tomo-Path.write.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.write 3 2025-04-19T14:30:40.366125 "Tomo man-pages" +.SH NAME +Path.write \- Writes the given text to the file at the specified path, creating the file if it doesn't already exist. Sets the file permissions as specified. If the file writing cannot be successfully completed, a runtime error is raised. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.write : func(path: Path, text: Text, permissions = Int32(0o644) -> Void)" +.fi + +.SH DESCRIPTION +Writes the given text to the file at the specified path, creating the file if it doesn't already exist. Sets the file permissions as specified. If the file writing cannot be successfully completed, a runtime error is raised. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path of the file to write to. - +text Text The text to write to the file. - +permissions The permissions to set on the file if it is created. Int32(0o644) +.TE +.SH RETURN +Nothing. + +.SH EXAMPLES +.EX +(./file.txt).write("Hello, world!") +.EE diff --git a/man/man3/tomo-Path.write_bytes.3 b/man/man3/tomo-Path.write_bytes.3 new file mode 100644 index 00000000..6cf31725 --- /dev/null +++ b/man/man3/tomo-Path.write_bytes.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.write_bytes 3 2025-04-19T14:30:40.366166 "Tomo man-pages" +.SH NAME +Path.write_bytes \- Writes the given bytes to the file at the specified path, creating the file if it doesn't already exist. Sets the file permissions as specified. If the file writing cannot be successfully completed, a runtime error is raised. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.write_bytes : func(path: Path, bytes: [Byte], permissions = Int32(0o644) -> Void)" +.fi + +.SH DESCRIPTION +Writes the given bytes to the file at the specified path, creating the file if it doesn't already exist. Sets the file permissions as specified. If the file writing cannot be successfully completed, a runtime error is raised. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The path of the file to write to. - +bytes [Byte] A list of bytes to write to the file. - +permissions The permissions to set on the file if it is created. Int32(0o644) +.TE +.SH RETURN +Nothing. + +.SH EXAMPLES +.EX +(./file.txt).write_bytes([104, 105]) +.EE diff --git a/man/man3/tomo-Path.write_unique.3 b/man/man3/tomo-Path.write_unique.3 new file mode 100644 index 00000000..cb93793b --- /dev/null +++ b/man/man3/tomo-Path.write_unique.3 @@ -0,0 +1,38 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.write_unique 3 2025-04-19T14:30:40.366203 "Tomo man-pages" +.SH NAME +Path.write_unique \- Writes the given text to a unique file path based on the specified path. The file is created if it doesn't exist. This is useful for creating temporary files. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.write_unique : func(path: Path, text: Text -> Path)" +.fi + +.SH DESCRIPTION +Writes the given text to a unique file path based on the specified path. The file is created if it doesn't exist. This is useful for creating temporary files. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The base path for generating the unique file. This path must include the string `XXXXXX` in the file base name. - +text Text The text to write to the file. - +.TE +.SH RETURN +The path of the newly created unique file. + +.SH EXAMPLES +.EX +>> created := (./file-XXXXXX.txt).write_unique("Hello, world!") += (./file-27QHtq.txt) +>> created.read() += "Hello, world!" +created.remove() +.EE diff --git a/man/man3/tomo-Path.write_unique_bytes.3 b/man/man3/tomo-Path.write_unique_bytes.3 new file mode 100644 index 00000000..0aae419f --- /dev/null +++ b/man/man3/tomo-Path.write_unique_bytes.3 @@ -0,0 +1,38 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Path.write_unique_bytes 3 2025-04-19T14:30:40.366241 "Tomo man-pages" +.SH NAME +Path.write_unique_bytes \- Writes the given bytes to a unique file path based on the specified path. The file is created if it doesn't exist. This is useful for creating temporary files. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Path.write_unique_bytes : func(path: Path, bytes: [Byte] -> Path)" +.fi + +.SH DESCRIPTION +Writes the given bytes to a unique file path based on the specified path. The file is created if it doesn't exist. This is useful for creating temporary files. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +path Path The base path for generating the unique file. This path must include the string `XXXXXX` in the file base name. - +bytes [Byte] The bytes to write to the file. - +.TE +.SH RETURN +The path of the newly created unique file. + +.SH EXAMPLES +.EX +>> created := (./file-XXXXXX.txt).write_unique_bytes([1, 2, 3]) += (./file-27QHtq.txt) +>> created.read() += [1, 2, 3] +created.remove() +.EE diff --git a/man/man3/tomo-Set.add.3 b/man/man3/tomo-Set.add.3 new file mode 100644 index 00000000..6ebfb5a4 --- /dev/null +++ b/man/man3/tomo-Set.add.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Set.add 3 2025-04-19T14:30:40.366278 "Tomo man-pages" +.SH NAME +Set.add \- Adds an item to the set. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Set.add : func(set: |T|, item: T -> Void)" +.fi + +.SH DESCRIPTION +Adds an item to the set. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +set |T| The mutable reference to the set. - +item T The item to add to the set. - +.TE +.SH RETURN +Nothing. + +.SH EXAMPLES +.EX +>> nums.add(42) +.EE diff --git a/man/man3/tomo-Set.add_all.3 b/man/man3/tomo-Set.add_all.3 new file mode 100644 index 00000000..97ccb88a --- /dev/null +++ b/man/man3/tomo-Set.add_all.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Set.add_all 3 2025-04-19T14:30:40.366315 "Tomo man-pages" +.SH NAME +Set.add_all \- Adds multiple items to the set. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Set.add_all : func(set: @|T|, items: [T] -> Void)" +.fi + +.SH DESCRIPTION +Adds multiple items to the set. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +set @|T| The mutable reference to the set. - +items [T] The list of items to add to the set. - +.TE +.SH RETURN +Nothing. + +.SH EXAMPLES +.EX +>> nums.add_all([1, 2, 3]) +.EE diff --git a/man/man3/tomo-Set.clear.3 b/man/man3/tomo-Set.clear.3 new file mode 100644 index 00000000..0d042f1d --- /dev/null +++ b/man/man3/tomo-Set.clear.3 @@ -0,0 +1,33 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Set.clear 3 2025-04-19T14:30:40.366350 "Tomo man-pages" +.SH NAME +Set.clear \- Removes all items from the set. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Set.clear : func(set: @|T| -> Void)" +.fi + +.SH DESCRIPTION +Removes all items from the set. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +set @|T| The mutable reference to the set. - +.TE +.SH RETURN +Nothing. + +.SH EXAMPLES +.EX +>> nums.clear() +.EE diff --git a/man/man3/tomo-Set.has.3 b/man/man3/tomo-Set.has.3 new file mode 100644 index 00000000..930658e5 --- /dev/null +++ b/man/man3/tomo-Set.has.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Set.has 3 2025-04-19T14:30:40.366403 "Tomo man-pages" +.SH NAME +Set.has \- Checks if the set contains a specified item. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Set.has : func(set: |T|, item: T -> Bool)" +.fi + +.SH DESCRIPTION +Checks if the set contains a specified item. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +set |T| The set to check. - +item T The item to check for presence. - +.TE +.SH RETURN +`yes` if the item is present, `no` otherwise. + +.SH EXAMPLES +.EX +>> |10, 20|.has(20) += yes +.EE diff --git a/man/man3/tomo-Set.is_subset_of.3 b/man/man3/tomo-Set.is_subset_of.3 new file mode 100644 index 00000000..0d52cffa --- /dev/null +++ b/man/man3/tomo-Set.is_subset_of.3 @@ -0,0 +1,36 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Set.is_subset_of 3 2025-04-19T14:30:40.366444 "Tomo man-pages" +.SH NAME +Set.is_subset_of \- Checks if the set is a subset of another set. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Set.is_subset_of : func(set: |T|, other: |T|, strict: Bool = no -> Bool)" +.fi + +.SH DESCRIPTION +Checks if the set is a subset of another set. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +set |T| The set to check. - +other |T| The set to compare against. - +strict Bool If `yes`, checks if the set is a strict subset (does not equal the other set). no +.TE +.SH RETURN +`yes` if the set is a subset of the other set (strictly or not), `no` otherwise. + +.SH EXAMPLES +.EX +>> |1, 2|.is_subset_of(|1, 2, 3|) += yes +.EE diff --git a/man/man3/tomo-Set.is_superset_of.3 b/man/man3/tomo-Set.is_superset_of.3 new file mode 100644 index 00000000..b3a81756 --- /dev/null +++ b/man/man3/tomo-Set.is_superset_of.3 @@ -0,0 +1,36 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Set.is_superset_of 3 2025-04-19T14:30:40.366494 "Tomo man-pages" +.SH NAME +Set.is_superset_of \- Checks if the set is a superset of another set. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Set.is_superset_of : func(set: |T|, other: |T|, strict: Bool = no -> Bool)" +.fi + +.SH DESCRIPTION +Checks if the set is a superset of another set. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +set |T| The set to check. - +other |T| The set to compare against. - +strict Bool If `yes`, checks if the set is a strict superset (does not equal the other set). no +.TE +.SH RETURN +`yes` if the set is a superset of the other set (strictly or not), `no` otherwise. + +.SH EXAMPLES +.EX +>> |1, 2, 3|.is_superset_of(|1, 2|) += yes +.EE diff --git a/man/man3/tomo-Set.overlap.3 b/man/man3/tomo-Set.overlap.3 new file mode 100644 index 00000000..9dccfa9b --- /dev/null +++ b/man/man3/tomo-Set.overlap.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Set.overlap 3 2025-04-19T14:30:40.366564 "Tomo man-pages" +.SH NAME +Set.overlap \- Creates a new set with items that are in both the original set and another set. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Set.overlap : func(set: |T|, other: |T| -> |T|)" +.fi + +.SH DESCRIPTION +Creates a new set with items that are in both the original set and another set. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +set |T| The original set. - +other |T| The set to intersect with. - +.TE +.SH RETURN +A new set containing only items present in both sets. + +.SH EXAMPLES +.EX +>> |1, 2|.overlap(|2, 3|) += |2| +.EE diff --git a/man/man3/tomo-Set.remove.3 b/man/man3/tomo-Set.remove.3 new file mode 100644 index 00000000..bc9c3291 --- /dev/null +++ b/man/man3/tomo-Set.remove.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Set.remove 3 2025-04-19T14:30:40.366605 "Tomo man-pages" +.SH NAME +Set.remove \- Removes an item from the set. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Set.remove : func(set: @|T|, item: T -> Void)" +.fi + +.SH DESCRIPTION +Removes an item from the set. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +set @|T| The mutable reference to the set. - +item T The item to remove from the set. - +.TE +.SH RETURN +Nothing. + +.SH EXAMPLES +.EX +>> nums.remove(42) +.EE diff --git a/man/man3/tomo-Set.remove_all.3 b/man/man3/tomo-Set.remove_all.3 new file mode 100644 index 00000000..3eae18d7 --- /dev/null +++ b/man/man3/tomo-Set.remove_all.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Set.remove_all 3 2025-04-19T14:30:40.366645 "Tomo man-pages" +.SH NAME +Set.remove_all \- Removes multiple items from the set. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Set.remove_all : func(set: @|T|, items: [T] -> Void)" +.fi + +.SH DESCRIPTION +Removes multiple items from the set. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +set @|T| The mutable reference to the set. - +items [T] The list of items to remove from the set. - +.TE +.SH RETURN +Nothing. + +.SH EXAMPLES +.EX +>> nums.remove_all([1, 2, 3]) +.EE diff --git a/man/man3/tomo-Set.with.3 b/man/man3/tomo-Set.with.3 new file mode 100644 index 00000000..54a38871 --- /dev/null +++ b/man/man3/tomo-Set.with.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Set.with 3 2025-04-19T14:30:40.366688 "Tomo man-pages" +.SH NAME +Set.with \- Creates a new set that is the union of the original set and another set. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Set.with : func(set: |T|, other: |T| -> |T|)" +.fi + +.SH DESCRIPTION +Creates a new set that is the union of the original set and another set. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +set |T| The original set. - +other |T| The set to union with. - +.TE +.SH RETURN +A new set containing all items from both sets. + +.SH EXAMPLES +.EX +>> |1, 2|.with(|2, 3|) += |1, 2, 3| +.EE diff --git a/man/man3/tomo-Set.without.3 b/man/man3/tomo-Set.without.3 new file mode 100644 index 00000000..ce0b95e4 --- /dev/null +++ b/man/man3/tomo-Set.without.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Set.without 3 2025-04-19T14:30:40.366726 "Tomo man-pages" +.SH NAME +Set.without \- Creates a new set with items from the original set but without items from another set. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Set.without : func(set: |T|, other: |T| -> |T|)" +.fi + +.SH DESCRIPTION +Creates a new set with items from the original set but without items from another set. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +set |T| The original set. - +other |T| The set of items to remove from the original set. - +.TE +.SH RETURN +A new set containing items from the original set excluding those in the other set. + +.SH EXAMPLES +.EX +>> |1, 2|.without(|2, 3|) += |1| +.EE diff --git a/man/man3/tomo-Table.clear.3 b/man/man3/tomo-Table.clear.3 new file mode 100644 index 00000000..5b61d5e7 --- /dev/null +++ b/man/man3/tomo-Table.clear.3 @@ -0,0 +1,33 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Table.clear 3 2025-04-19T14:30:40.366765 "Tomo man-pages" +.SH NAME +Table.clear \- Removes all key-value pairs from the table. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Table.clear : func(t: &{K=V} -> Void)" +.fi + +.SH DESCRIPTION +Removes all key-value pairs from the table. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +t &{K=V} The reference to the table. - +.TE +.SH RETURN +Nothing. + +.SH EXAMPLES +.EX +>> t.clear() +.EE diff --git a/man/man3/tomo-Table.get.3 b/man/man3/tomo-Table.get.3 new file mode 100644 index 00000000..8d336835 --- /dev/null +++ b/man/man3/tomo-Table.get.3 @@ -0,0 +1,45 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Table.get 3 2025-04-19T14:30:40.366804 "Tomo man-pages" +.SH NAME +Table.get \- Retrieves the value associated with a key, or returns `none` if the key is not present. **Note:** default values for the table are ignored. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Table.get : func(t: {K=V}, key: K -> V?)" +.fi + +.SH DESCRIPTION +Retrieves the value associated with a key, or returns `none` if the key is not present. **Note:** default values for the table are ignored. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +t {K=V} The table. - +key K The key whose associated value is to be retrieved. - +.TE +.SH RETURN +The value associated with the key or `none` if the key is not found. + +.SH EXAMPLES +.EX +>> t := {"A"=1, "B"=2} +>> t.get("A") += 1? + +>> t.get("????") += none + +>> t.get("A")! += 1 + +>> t.get("????") or 0 += 0 +.EE diff --git a/man/man3/tomo-Table.get_or_set.3 b/man/man3/tomo-Table.get_or_set.3 new file mode 100644 index 00000000..bd39773c --- /dev/null +++ b/man/man3/tomo-Table.get_or_set.3 @@ -0,0 +1,48 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Table.get_or_set 3 2025-04-19T14:30:40.366848 "Tomo man-pages" +.SH NAME +Table.get_or_set \- If the given key is in the table, return the associated value. Otherwise, insert the given default value into the table and return it. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Table.get_or_set : func(t: &{K=V}, key: K, default: V -> V?)" +.fi + +.SH DESCRIPTION +If the given key is in the table, return the associated value. Otherwise, insert the given default value into the table and return it. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +t &{K=V} The table. - +key K The key whose associated value is to be retrieved. - +default V The default value to insert and return if the key is not present in the table. - +.TE +.SH RETURN +Either the value associated with the key (if present) or the default value. The table will be mutated if the key is not already present. + +.SH NOTES +If no default value is provided explicitly, but the table has a default value associated with it, the table's default value will be used. +The default value is only evaluated if the key is missing. + +.SH EXAMPLES +.EX +>> t := &{"A"=@[1, 2, 3]; default=@[]} +>> t.get_or_set("A").insert(4) +>> t.get_or_set("B").insert(99) +>> t += &{"A"=@[1, 2, 3, 4], "B"=@[99]} + +>> t.get_or_set("C", @[0, 0, 0]) += @[0, 0, 0] +>> t += &{"A"=@[1, 2, 3, 4], "B"=@[99], "C"=@[0, 0, 0]} +.EE diff --git a/man/man3/tomo-Table.has.3 b/man/man3/tomo-Table.has.3 new file mode 100644 index 00000000..d1ad6350 --- /dev/null +++ b/man/man3/tomo-Table.has.3 @@ -0,0 +1,37 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Table.has 3 2025-04-19T14:30:40.366893 "Tomo man-pages" +.SH NAME +Table.has \- Checks if the table contains a specified key. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Table.has : func(t: {K=V}, key: K -> Bool)" +.fi + +.SH DESCRIPTION +Checks if the table contains a specified key. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +t {K=V} The table. - +key K The key to check for presence. - +.TE +.SH RETURN +`yes` if the key is present, `no` otherwise. + +.SH EXAMPLES +.EX +>> {"A"=1, "B"=2}.has("A") += yes +>> {"A"=1, "B"=2}.has("xxx") += no +.EE diff --git a/man/man3/tomo-Table.remove.3 b/man/man3/tomo-Table.remove.3 new file mode 100644 index 00000000..2ea6e833 --- /dev/null +++ b/man/man3/tomo-Table.remove.3 @@ -0,0 +1,37 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Table.remove 3 2025-04-19T14:30:40.366935 "Tomo man-pages" +.SH NAME +Table.remove \- Removes the key-value pair associated with a specified key. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Table.remove : func(t: {K=V}, key: K -> Void)" +.fi + +.SH DESCRIPTION +Removes the key-value pair associated with a specified key. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +t {K=V} The reference to the table. - +key K The key of the key-value pair to remove. - +.TE +.SH RETURN +Nothing. + +.SH EXAMPLES +.EX +t := {"A"=1, "B"=2} +t.remove("A") +>> t += {"B"=2} +.EE diff --git a/man/man3/tomo-Table.set.3 b/man/man3/tomo-Table.set.3 new file mode 100644 index 00000000..86646f42 --- /dev/null +++ b/man/man3/tomo-Table.set.3 @@ -0,0 +1,38 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Table.set 3 2025-04-19T14:30:40.366976 "Tomo man-pages" +.SH NAME +Table.set \- Sets or updates the value associated with a specified key. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Table.set : func(t: {K=V}, key: K, value: V -> Void)" +.fi + +.SH DESCRIPTION +Sets or updates the value associated with a specified key. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +t {K=V} The reference to the table. - +key K The key to set or update. - +value V The value to associate with the key. - +.TE +.SH RETURN +Nothing. + +.SH EXAMPLES +.EX +t := {"A"=1, "B"=2} +t.set("C", 3) +>> t += {"A"=1, "B"=2, "C"=3} +.EE diff --git a/man/man3/tomo-Text.as_c_string.3 b/man/man3/tomo-Text.as_c_string.3 new file mode 100644 index 00000000..9933b17a --- /dev/null +++ b/man/man3/tomo-Text.as_c_string.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.as_c_string 3 2025-04-19T14:30:40.367014 "Tomo man-pages" +.SH NAME +Text.as_c_string \- Converts a `Text` value to a C-style string. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.as_c_string : func(text: Text -> CString)" +.fi + +.SH DESCRIPTION +Converts a `Text` value to a C-style string. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to be converted to a C-style string. - +.TE +.SH RETURN +A C-style string (`CString`) representing the text. + +.SH EXAMPLES +.EX +>> "Hello".as_c_string() += CString("Hello") +.EE diff --git a/man/man3/tomo-Text.at.3 b/man/man3/tomo-Text.at.3 new file mode 100644 index 00000000..50693494 --- /dev/null +++ b/man/man3/tomo-Text.at.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.at 3 2025-04-19T14:30:40.367051 "Tomo man-pages" +.SH NAME +Text.at \- Get the graphical cluster at a given index. This is similar to `str[i]` with ASCII text, but has more correct behavior for unicode text. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.at : func(text: Text, index: Int -> Text)" +.fi + +.SH DESCRIPTION +Get the graphical cluster at a given index. This is similar to `str[i]` with ASCII text, but has more correct behavior for unicode text. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text from which to get a cluster. - +index Int The index of the graphical cluster (1-indexed). - +.TE +.SH RETURN +A `Text` with the single graphical cluster at the given index. Note: negative indices are counted from the back of the text, so `-1` means the last cluster, `-2` means the second-to-last, and so on. + +.SH EXAMPLES +.EX +>> "Amélie".at(3) += "é" +.EE diff --git a/man/man3/tomo-Text.by_line.3 b/man/man3/tomo-Text.by_line.3 new file mode 100644 index 00000000..a5066e66 --- /dev/null +++ b/man/man3/tomo-Text.by_line.3 @@ -0,0 +1,39 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.by_line 3 2025-04-19T14:30:40.367111 "Tomo man-pages" +.SH NAME +Text.by_line \- Returns an iterator function that can be used to iterate over the lines in a text. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.by_line : func(text: Text -> func(->Text?))" +.fi + +.SH DESCRIPTION +Returns an iterator function that can be used to iterate over the lines in a text. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to be iterated over, line by line. - +.TE +.SH RETURN +An iterator function that returns one line at a time, until it runs out and returns `none`. **Note:** this function ignores a trailing newline if there is one. If you don't want this behavior, use `text.by_split($/{1 nl}/)` instead. + +.SH EXAMPLES +.EX +text := " +line one +line two +" +for line in text.by_line() +# Prints: "line one" then "line two": +say(line) +.EE diff --git a/man/man3/tomo-Text.by_split.3 b/man/man3/tomo-Text.by_split.3 new file mode 100644 index 00000000..ad585f50 --- /dev/null +++ b/man/man3/tomo-Text.by_split.3 @@ -0,0 +1,40 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.by_split 3 2025-04-19T14:30:40.367152 "Tomo man-pages" +.SH NAME +Text.by_split \- Returns an iterator function that can be used to iterate over text separated by a delimiter. **Note:** to split based on a set of delimiters, use [`by_split_any()`](#by_split_any). + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.by_split : func(text: Text, delimiter: Text = "" -> func(->Text?))" +.fi + +.SH DESCRIPTION +Returns an iterator function that can be used to iterate over text separated by a delimiter. **Note:** to split based on a set of delimiters, use [`by_split_any()`](#by_split_any). + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to be iterated over in delimited chunks. - +delimiter Text An exact delimiter to use for splitting the text. "" +.TE +.SH RETURN +An iterator function that returns one chunk of text at a time, separated by the given delimiter, until it runs out and returns `none`. **Note:** using an empty delimiter (the default) will iterate over single grapheme clusters in the text. + +.SH NOTES +If an empty text is given as the delimiter, then each split will be the graphical clusters of the text. + +.SH EXAMPLES +.EX +text := "one,two,three" +for chunk in text.by_split(",") +# Prints: "one" then "two" then "three": +say(chunk) +.EE diff --git a/man/man3/tomo-Text.by_split_any.3 b/man/man3/tomo-Text.by_split_any.3 new file mode 100644 index 00000000..e7b361f1 --- /dev/null +++ b/man/man3/tomo-Text.by_split_any.3 @@ -0,0 +1,40 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.by_split_any 3 2025-04-19T14:30:40.367193 "Tomo man-pages" +.SH NAME +Text.by_split_any \- Returns an iterator function that can be used to iterate over text separated by one or more characters (grapheme clusters) from a given text of delimiters. **Note:** to split based on an exact delimiter, use [`by_split()`](#by_split). + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.by_split_any : func(text: Text, delimiters: Text = " $\\t\\r\\n" -> func(->Text?))" +.fi + +.SH DESCRIPTION +Returns an iterator function that can be used to iterate over text separated by one or more characters (grapheme clusters) from a given text of delimiters. **Note:** to split based on an exact delimiter, use [`by_split()`](#by_split). + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to be iterated over in delimited chunks. - +delimiters Text Grapheme clusters to use for splitting the text. " $\\t\\r\\n" +.TE +.SH RETURN +An iterator function that returns one chunk of text at a time, separated by the given delimiter characters, until it runs out and returns `none`. + +.SH NOTES +Splitting will occur on every place where one or more of the grapheme clusters in `delimiters` occurs. + +.SH EXAMPLES +.EX +text := "one,two,;,three" +for chunk in text.by_split_any(",;") +# Prints: "one" then "two" then "three": +say(chunk) +.EE diff --git a/man/man3/tomo-Text.bytes.3 b/man/man3/tomo-Text.bytes.3 new file mode 100644 index 00000000..3f45e6a7 --- /dev/null +++ b/man/man3/tomo-Text.bytes.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.bytes 3 2025-04-19T14:30:40.367234 "Tomo man-pages" +.SH NAME +Text.bytes \- Converts a `Text` value to a list of bytes representing a UTF8 encoding of the text. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.bytes : func(text: Text -> [Byte])" +.fi + +.SH DESCRIPTION +Converts a `Text` value to a list of bytes representing a UTF8 encoding of the text. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to be converted to UTF8 bytes. - +.TE +.SH RETURN +A list of bytes (`[Byte]`) representing the text in UTF8 encoding. + +.SH EXAMPLES +.EX +>> "Amélie".bytes() += [65, 109, 195, 169, 108, 105, 101] +.EE diff --git a/man/man3/tomo-Text.caseless_equals.3 b/man/man3/tomo-Text.caseless_equals.3 new file mode 100644 index 00000000..e202bd22 --- /dev/null +++ b/man/man3/tomo-Text.caseless_equals.3 @@ -0,0 +1,40 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.caseless_equals 3 2025-04-19T14:30:40.367273 "Tomo man-pages" +.SH NAME +Text.caseless_equals \- Checks whether two texts are equal, ignoring the casing of the letters (i.e. case-insensitive comparison). + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.caseless_equals : func(a: Text, b: Text, language: Text = "C" -> Bool)" +.fi + +.SH DESCRIPTION +Checks whether two texts are equal, ignoring the casing of the letters (i.e. case-insensitive comparison). + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +a Text The first text to compare case-insensitively. - +b Text The second text to compare case-insensitively. - +language Text The ISO 639 language code for which casing rules to use. "C" +.TE +.SH RETURN +`yes` if `a` and `b` are equal to each other, ignoring casing, otherwise `no`. + +.SH EXAMPLES +.EX +>> "A".caseless_equals("a") += yes + +# Turkish lowercase "I" is "ı" (dotless I), not "i" +>> "I".caseless_equals("i", language="tr_TR") += no +.EE diff --git a/man/man3/tomo-Text.codepoint_names.3 b/man/man3/tomo-Text.codepoint_names.3 new file mode 100644 index 00000000..b33f5a86 --- /dev/null +++ b/man/man3/tomo-Text.codepoint_names.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.codepoint_names 3 2025-04-19T14:30:40.367316 "Tomo man-pages" +.SH NAME +Text.codepoint_names \- Returns a list of the names of each codepoint in the text. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.codepoint_names : func(text: Text -> [Text])" +.fi + +.SH DESCRIPTION +Returns a list of the names of each codepoint in the text. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text from which to extract codepoint names. - +.TE +.SH RETURN +A list of codepoint names (`[Text]`). + +.SH EXAMPLES +.EX +>> "Amélie".codepoint_names() += ["LATIN CAPITAL LETTER A", "LATIN SMALL LETTER M", "LATIN SMALL LETTER E WITH ACUTE", "LATIN SMALL LETTER L", "LATIN SMALL LETTER I", "LATIN SMALL LETTER E"] +.EE diff --git a/man/man3/tomo-Text.ends_with.3 b/man/man3/tomo-Text.ends_with.3 new file mode 100644 index 00000000..cb991cc2 --- /dev/null +++ b/man/man3/tomo-Text.ends_with.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.ends_with 3 2025-04-19T14:30:40.367353 "Tomo man-pages" +.SH NAME +Text.ends_with \- Checks if the `Text` ends with a literal suffix text. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.ends_with : func(text: Text, suffix: Text -> Bool)" +.fi + +.SH DESCRIPTION +Checks if the `Text` ends with a literal suffix text. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to be searched. - +suffix Text The literal suffix text to check for. - +.TE +.SH RETURN +`yes` if the text has the target, `no` otherwise. + +.SH EXAMPLES +.EX +>> "hello world".ends_with("world") += yes +.EE diff --git a/man/man3/tomo-Text.from.3 b/man/man3/tomo-Text.from.3 new file mode 100644 index 00000000..caf232e5 --- /dev/null +++ b/man/man3/tomo-Text.from.3 @@ -0,0 +1,38 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.from 3 2025-04-19T14:30:40.367391 "Tomo man-pages" +.SH NAME +Text.from \- Get a slice of the text, starting at the given position. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.from : func(text: Text, first: Int -> Text)" +.fi + +.SH DESCRIPTION +Get a slice of the text, starting at the given position. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to be sliced. - +first Int The index to begin the slice. - +.TE +.SH RETURN +The text from the given grapheme cluster to the end of the text. Note: a negative index counts backwards from the end of the text, so `-1` refers to the last cluster, `-2` the second-to-last, etc. Slice ranges will be truncated to the length of the text. + +.SH EXAMPLES +.EX +>> "hello".from(2) += "ello" + +>> "hello".from(-2) += "lo" +.EE diff --git a/man/man3/tomo-Text.from_bytes.3 b/man/man3/tomo-Text.from_bytes.3 new file mode 100644 index 00000000..2bcdccfb --- /dev/null +++ b/man/man3/tomo-Text.from_bytes.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.from_bytes 3 2025-04-19T14:30:40.367429 "Tomo man-pages" +.SH NAME +Text.from_bytes \- Returns text that has been constructed from the given UTF8 bytes. Note: the text will be normalized, so the resulting text's UTF8 bytes may not exactly match the input. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.from_bytes : func(bytes: [Byte] -> [Text])" +.fi + +.SH DESCRIPTION +Returns text that has been constructed from the given UTF8 bytes. Note: the text will be normalized, so the resulting text's UTF8 bytes may not exactly match the input. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +bytes [Byte] The UTF-8 bytes of the desired text. - +.TE +.SH RETURN +A new text based on the input UTF8 bytes after normalization has been applied. + +.SH EXAMPLES +.EX +>> Text.from_bytes([195, 133, 107, 101]) += "Åke" +.EE diff --git a/man/man3/tomo-Text.from_c_string.3 b/man/man3/tomo-Text.from_c_string.3 new file mode 100644 index 00000000..99cbb233 --- /dev/null +++ b/man/man3/tomo-Text.from_c_string.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.from_c_string 3 2025-04-19T14:30:40.367465 "Tomo man-pages" +.SH NAME +Text.from_c_string \- Converts a C-style string to a `Text` value. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.from_c_string : func(str: CString -> Text)" +.fi + +.SH DESCRIPTION +Converts a C-style string to a `Text` value. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +str CString The C-style string to be converted. - +.TE +.SH RETURN +A `Text` value representing the C-style string. + +.SH EXAMPLES +.EX +>> Text.from_c_string(CString("Hello")) += "Hello" +.EE diff --git a/man/man3/tomo-Text.from_codepoint_names.3 b/man/man3/tomo-Text.from_codepoint_names.3 new file mode 100644 index 00000000..2d0dd186 --- /dev/null +++ b/man/man3/tomo-Text.from_codepoint_names.3 @@ -0,0 +1,38 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.from_codepoint_names 3 2025-04-19T14:30:40.367510 "Tomo man-pages" +.SH NAME +Text.from_codepoint_names \- Returns text that has the given codepoint names (according to the Unicode specification) as its codepoints. Note: the text will be normalized, so the resulting text's codepoints may not exactly match the input codepoints. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.from_codepoint_names : func(codepoint_names: [Text] -> [Text])" +.fi + +.SH DESCRIPTION +Returns text that has the given codepoint names (according to the Unicode specification) as its codepoints. Note: the text will be normalized, so the resulting text's codepoints may not exactly match the input codepoints. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +codepoint_names [Text] The names of each codepoint in the desired text (case-insentive). - +.TE +.SH RETURN +A new text with the specified codepoints after normalization has been applied. Any invalid names are ignored. + +.SH EXAMPLES +.EX +>> Text.from_codepoint_names([ +"LATIN CAPITAL LETTER A WITH RING ABOVE", +"LATIN SMALL LETTER K", +"LATIN SMALL LETTER E", +] += "Åke" +.EE diff --git a/man/man3/tomo-Text.from_codepoints.3 b/man/man3/tomo-Text.from_codepoints.3 new file mode 100644 index 00000000..7bcb72cb --- /dev/null +++ b/man/man3/tomo-Text.from_codepoints.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.from_codepoints 3 2025-04-19T14:30:40.367551 "Tomo man-pages" +.SH NAME +Text.from_codepoints \- Returns text that has been constructed from the given UTF32 codepoints. Note: the text will be normalized, so the resulting text's codepoints may not exactly match the input codepoints. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.from_codepoints : func(codepoints: [Int32] -> [Text])" +.fi + +.SH DESCRIPTION +Returns text that has been constructed from the given UTF32 codepoints. Note: the text will be normalized, so the resulting text's codepoints may not exactly match the input codepoints. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +codepoints [Int32] The UTF32 codepoints in the desired text. - +.TE +.SH RETURN +A new text with the specified codepoints after normalization has been applied. + +.SH EXAMPLES +.EX +>> Text.from_codepoints([197, 107, 101]) += "Åke" +.EE diff --git a/man/man3/tomo-Text.has.3 b/man/man3/tomo-Text.has.3 new file mode 100644 index 00000000..7cd8564d --- /dev/null +++ b/man/man3/tomo-Text.has.3 @@ -0,0 +1,37 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.has 3 2025-04-19T14:30:40.367609 "Tomo man-pages" +.SH NAME +Text.has \- Checks if the `Text` contains some target text. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.has : func(text: Text, target: Text -> Bool)" +.fi + +.SH DESCRIPTION +Checks if the `Text` contains some target text. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to be searched. - +target Text The text to search for. - +.TE +.SH RETURN +`yes` if the target text is found, `no` otherwise. + +.SH EXAMPLES +.EX +>> "hello world".has("wo") += yes +>> "hello world".has("xxx") += no +.EE diff --git a/man/man3/tomo-Text.join.3 b/man/man3/tomo-Text.join.3 new file mode 100644 index 00000000..e98390a0 --- /dev/null +++ b/man/man3/tomo-Text.join.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.join 3 2025-04-19T14:30:40.367649 "Tomo man-pages" +.SH NAME +Text.join \- Joins a list of text pieces with a specified glue. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.join : func(glue: Text, pieces: [Text] -> Text)" +.fi + +.SH DESCRIPTION +Joins a list of text pieces with a specified glue. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +glue Text The text used to join the pieces. - +pieces [Text] The list of text pieces to be joined. - +.TE +.SH RETURN +A single `Text` value with the pieces joined by the glue. + +.SH EXAMPLES +.EX +>> ", ".join(["one", "two", "three"]) += "one, two, three" +.EE diff --git a/man/man3/tomo-Text.left_pad.3 b/man/man3/tomo-Text.left_pad.3 new file mode 100644 index 00000000..c8e25cf8 --- /dev/null +++ b/man/man3/tomo-Text.left_pad.3 @@ -0,0 +1,39 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.left_pad 3 2025-04-19T14:30:40.367729 "Tomo man-pages" +.SH NAME +Text.left_pad \- Pad some text on the left side so it reaches a target width. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.left_pad : func(text: Text, width: Int, pad: Text = " ", language: Text = "C" -> Text)" +.fi + +.SH DESCRIPTION +Pad some text on the left side so it reaches a target width. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to pad. - +width Int The target width. - +pad Text The padding text. " " +language Text The ISO 639 language code for which character width to use. "C" +.TE +.SH RETURN +Text with length at least `width`, with extra padding on the left as needed. If `pad` has length greater than 1, it may be partially repeated to reach the exact desired length. + +.SH EXAMPLES +.EX +>> "x".left_pad(5) += " x" +>> "x".left_pad(5, "ABC") += "ABCAx" +.EE diff --git a/man/man3/tomo-Text.lines.3 b/man/man3/tomo-Text.lines.3 new file mode 100644 index 00000000..78ecf7dc --- /dev/null +++ b/man/man3/tomo-Text.lines.3 @@ -0,0 +1,42 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.lines 3 2025-04-19T14:30:40.367769 "Tomo man-pages" +.SH NAME +Text.lines \- Splits the text into a list of lines of text, preserving blank lines, ignoring trailing newlines, and handling `\r\n` the same as `\n`. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.lines : func(text: Text -> [Text])" +.fi + +.SH DESCRIPTION +Splits the text into a list of lines of text, preserving blank lines, ignoring trailing newlines, and handling `\r\n` the same as `\n`. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to be split into lines. - +.TE +.SH RETURN +A list of substrings resulting from the split. + +.SH EXAMPLES +.EX +>> "one\\ntwo\\nthree".lines() += ["one", "two", "three"] +>> "one\\ntwo\\nthree\\n".lines() += ["one", "two", "three"] +>> "one\\ntwo\\nthree\\n\\n".lines() += ["one", "two", "three", ""] +>> "one\\r\\ntwo\\r\\nthree\\r\\n".lines() += ["one", "two", "three"] +>> "".lines() += [] +.EE diff --git a/man/man3/tomo-Text.lower.3 b/man/man3/tomo-Text.lower.3 new file mode 100644 index 00000000..9d9251bb --- /dev/null +++ b/man/man3/tomo-Text.lower.3 @@ -0,0 +1,38 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.lower 3 2025-04-19T14:30:40.367810 "Tomo man-pages" +.SH NAME +Text.lower \- Converts all characters in the text to lowercase. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.lower : func(text: Text, language: Text = "C" -> Text)" +.fi + +.SH DESCRIPTION +Converts all characters in the text to lowercase. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to be converted to lowercase. - +language Text The ISO 639 language code for which casing rules to use. "C" +.TE +.SH RETURN +The lowercase version of the text. + +.SH EXAMPLES +.EX +>> "AMÉLIE".lower() += "amélie" + +>> "I".lower(language="tr_TR") +>> "ı" +.EE diff --git a/man/man3/tomo-Text.middle_pad.3 b/man/man3/tomo-Text.middle_pad.3 new file mode 100644 index 00000000..84600daa --- /dev/null +++ b/man/man3/tomo-Text.middle_pad.3 @@ -0,0 +1,39 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.middle_pad 3 2025-04-19T14:30:40.367688 "Tomo man-pages" +.SH NAME +Text.middle_pad \- Pad some text on the left and right side so it reaches a target width. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.middle_pad : func(text: Text, width: Int, pad: Text = " ", language: Text = "C" -> Text)" +.fi + +.SH DESCRIPTION +Pad some text on the left and right side so it reaches a target width. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to pad. - +width Int The target width. - +pad Text The padding text. " " +language Text The ISO 639 language code for which character width to use. "C" +.TE +.SH RETURN +Text with length at least `width`, with extra padding on the left and right as needed. If `pad` has length greater than 1, it may be partially repeated to reach the exact desired length. + +.SH EXAMPLES +.EX +>> "x".middle_pad(6) += " x " +>> "x".middle_pad(10, "ABC") += "ABCAxABCAB" +.EE diff --git a/man/man3/tomo-Text.quoted.3 b/man/man3/tomo-Text.quoted.3 new file mode 100644 index 00000000..08f14d2f --- /dev/null +++ b/man/man3/tomo-Text.quoted.3 @@ -0,0 +1,36 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.quoted 3 2025-04-19T14:30:40.367849 "Tomo man-pages" +.SH NAME +Text.quoted \- Formats the text with quotation marks and escapes. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.quoted : func(text: Text, color: Bool = no, quotation_mark: Text = `"` -> Text)" +.fi + +.SH DESCRIPTION +Formats the text with quotation marks and escapes. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to be quoted. - +color Bool Whether to add color formatting. no +quotation_mark Text The quotation mark to use. `"` +.TE +.SH RETURN +The text formatted as a quoted text. + +.SH EXAMPLES +.EX +>> "one\\ntwo".quoted() += "\\"one\\\\ntwo\\"" +.EE diff --git a/man/man3/tomo-Text.repeat.3 b/man/man3/tomo-Text.repeat.3 new file mode 100644 index 00000000..8dd62806 --- /dev/null +++ b/man/man3/tomo-Text.repeat.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.repeat 3 2025-04-19T14:30:40.367888 "Tomo man-pages" +.SH NAME +Text.repeat \- Repeat some text multiple times. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.repeat : func(text: Text, count: Int -> Text)" +.fi + +.SH DESCRIPTION +Repeat some text multiple times. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to repeat. - +count Int The number of times to repeat it. (Negative numbers are equivalent to zero). - +.TE +.SH RETURN +The text repeated the given number of times. + +.SH EXAMPLES +.EX +>> "Abc".repeat(3) += "AbcAbcAbc" +.EE diff --git a/man/man3/tomo-Text.replace.3 b/man/man3/tomo-Text.replace.3 new file mode 100644 index 00000000..4b7993fc --- /dev/null +++ b/man/man3/tomo-Text.replace.3 @@ -0,0 +1,36 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.replace 3 2025-04-19T14:30:40.367925 "Tomo man-pages" +.SH NAME +Text.replace \- Replaces occurrences of a target text with a replacement text. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.replace : func(text: Text, target: Text, replacement: Text -> Text)" +.fi + +.SH DESCRIPTION +Replaces occurrences of a target text with a replacement text. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text in which to perform replacements. - +target Text The target text to be replaced. - +replacement Text The text to replace the target with. - +.TE +.SH RETURN +The text with occurrences of the target replaced. + +.SH EXAMPLES +.EX +>> "Hello world".replace("world", "there") += "Hello there" +.EE diff --git a/man/man3/tomo-Text.reversed.3 b/man/man3/tomo-Text.reversed.3 new file mode 100644 index 00000000..6966877b --- /dev/null +++ b/man/man3/tomo-Text.reversed.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.reversed 3 2025-04-19T14:30:40.367963 "Tomo man-pages" +.SH NAME +Text.reversed \- Return a text that has the grapheme clusters in reverse order. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.reversed : func(text: Text -> Text)" +.fi + +.SH DESCRIPTION +Return a text that has the grapheme clusters in reverse order. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to reverse. - +.TE +.SH RETURN +A reversed version of the text. + +.SH EXAMPLES +.EX +>> "Abc".reversed() += "cbA" +.EE diff --git a/man/man3/tomo-Text.right_pad.3 b/man/man3/tomo-Text.right_pad.3 new file mode 100644 index 00000000..3fc5b404 --- /dev/null +++ b/man/man3/tomo-Text.right_pad.3 @@ -0,0 +1,39 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.right_pad 3 2025-04-19T14:30:40.367999 "Tomo man-pages" +.SH NAME +Text.right_pad \- Pad some text on the right side so it reaches a target width. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.right_pad : func(text: Text, width: Int, pad: Text = " ", language: Text = "C" -> Text)" +.fi + +.SH DESCRIPTION +Pad some text on the right side so it reaches a target width. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to pad. - +width Int The target width. - +pad Text The padding text. " " +language Text The ISO 639 language code for which character width to use. "C" +.TE +.SH RETURN +Text with length at least `width`, with extra padding on the right as needed. If `pad` has length greater than 1, it may be partially repeated to reach the exact desired length. + +.SH EXAMPLES +.EX +>> "x".right_pad(5) += "x " +>> "x".right_pad(5, "ABC") += "xABCA" +.EE diff --git a/man/man3/tomo-Text.slice.3 b/man/man3/tomo-Text.slice.3 new file mode 100644 index 00000000..8c4cd9f0 --- /dev/null +++ b/man/man3/tomo-Text.slice.3 @@ -0,0 +1,42 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.slice 3 2025-04-19T14:30:40.368043 "Tomo man-pages" +.SH NAME +Text.slice \- Get a slice of the text. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.slice : func(text: Text, from: Int = 1, to: Int = -1 -> Text)" +.fi + +.SH DESCRIPTION +Get a slice of the text. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to be sliced. - +from Int The index of the first grapheme cluster to include (1-indexed). 1 +to Int The index of the last grapheme cluster to include (1-indexed). -1 +.TE +.SH RETURN +The text that spans the given grapheme cluster indices. Note: a negative index counts backwards from the end of the text, so `-1` refers to the last cluster, `-2` the second-to-last, etc. Slice ranges will be truncated to the length of the text. + +.SH EXAMPLES +.EX +>> "hello".slice(2, 3) += "el" + +>> "hello".slice(to=-2) += "hell" + +>> "hello".slice(from=2) += "ello" +.EE diff --git a/man/man3/tomo-Text.split.3 b/man/man3/tomo-Text.split.3 new file mode 100644 index 00000000..5c6bf034 --- /dev/null +++ b/man/man3/tomo-Text.split.3 @@ -0,0 +1,38 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.split 3 2025-04-19T14:30:40.368084 "Tomo man-pages" +.SH NAME +Text.split \- Splits the text into a list of substrings based on exact matches of a delimiter. **Note:** to split based on a set of delimiter characters, use [`split_any()`](#split_any). + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.split : func(text: Text, delimiter: Text = "" -> [Text])" +.fi + +.SH DESCRIPTION +Splits the text into a list of substrings based on exact matches of a delimiter. **Note:** to split based on a set of delimiter characters, use [`split_any()`](#split_any). + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to be split. - +delimiter Text The delimiter used to split the text. If the delimiter is the empty text, the text will be split into individual grapheme clusters. "" +.TE +.SH RETURN +A list of subtexts resulting from the split. + +.SH EXAMPLES +.EX +>> "one,two,,three".split(",") += ["one", "two", "", "three"] + +>> "abc".split() += ["a", "b", "c"] +.EE diff --git a/man/man3/tomo-Text.split_any.3 b/man/man3/tomo-Text.split_any.3 new file mode 100644 index 00000000..dc91b796 --- /dev/null +++ b/man/man3/tomo-Text.split_any.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.split_any 3 2025-04-19T14:30:40.368129 "Tomo man-pages" +.SH NAME +Text.split_any \- Splits the text into a list of substrings at one or more occurrences of a set of delimiter characters (grapheme clusters). **Note:** to split based on an exact delimiter, use [`split()`](#split). + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.split_any : func(text: Text, delimiters: Text = " $\\t\\r\\n" -> [Text])" +.fi + +.SH DESCRIPTION +Splits the text into a list of substrings at one or more occurrences of a set of delimiter characters (grapheme clusters). **Note:** to split based on an exact delimiter, use [`split()`](#split). + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to be split. - +delimiters Text A text containing multiple delimiters to be used for splitting the text into chunks. " $\\t\\r\\n" +.TE +.SH RETURN +A list of subtexts resulting from the split. + +.SH EXAMPLES +.EX +>> "one, two,,three".split_any(", ") += ["one", "two", "three"] +.EE diff --git a/man/man3/tomo-Text.starts_with.3 b/man/man3/tomo-Text.starts_with.3 new file mode 100644 index 00000000..7f3d3bd8 --- /dev/null +++ b/man/man3/tomo-Text.starts_with.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.starts_with 3 2025-04-19T14:30:40.368184 "Tomo man-pages" +.SH NAME +Text.starts_with \- Checks if the `Text` starts with a literal prefix text. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.starts_with : func(text: Text, prefix: Text -> Bool)" +.fi + +.SH DESCRIPTION +Checks if the `Text` starts with a literal prefix text. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to be searched. - +prefix Text The literal prefix text to check for. - +.TE +.SH RETURN +`yes` if the text has the given prefix, `no` otherwise. + +.SH EXAMPLES +.EX +>> "hello world".starts_with("hello") += yes +.EE diff --git a/man/man3/tomo-Text.title.3 b/man/man3/tomo-Text.title.3 new file mode 100644 index 00000000..0204d2ad --- /dev/null +++ b/man/man3/tomo-Text.title.3 @@ -0,0 +1,39 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.title 3 2025-04-19T14:30:40.368227 "Tomo man-pages" +.SH NAME +Text.title \- Converts the text to title case (capitalizing the first letter of each word). + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.title : func(text: Text, language: Text = "C" -> Text)" +.fi + +.SH DESCRIPTION +Converts the text to title case (capitalizing the first letter of each word). + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to be converted to title case. - +language Text The ISO 639 language code for which casing rules to use. "C" +.TE +.SH RETURN +The text in title case. + +.SH EXAMPLES +.EX +>> "amélie".title() += "Amélie" + +# In Turkish, uppercase "i" is "İ" +>> "i".title(language="tr_TR") += "İ" +.EE diff --git a/man/man3/tomo-Text.to.3 b/man/man3/tomo-Text.to.3 new file mode 100644 index 00000000..bc95fa9e --- /dev/null +++ b/man/man3/tomo-Text.to.3 @@ -0,0 +1,38 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.to 3 2025-04-19T14:30:40.368269 "Tomo man-pages" +.SH NAME +Text.to \- Get a slice of the text, ending at the given position. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.to : func(text: Text, last: Int -> Text)" +.fi + +.SH DESCRIPTION +Get a slice of the text, ending at the given position. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to be sliced. - +last Int The index of the last grapheme cluster to include (1-indexed). - +.TE +.SH RETURN +The text up to and including the given grapheme cluster. Note: a negative index counts backwards from the end of the text, so `-1` refers to the last cluster, `-2` the second-to-last, etc. Slice ranges will be truncated to the length of the text. + +.SH EXAMPLES +.EX +>> "goodbye".to(3) += "goo" + +>> "goodbye".to(-2) += "goodby" +.EE diff --git a/man/man3/tomo-Text.translate.3 b/man/man3/tomo-Text.translate.3 new file mode 100644 index 00000000..eaca1312 --- /dev/null +++ b/man/man3/tomo-Text.translate.3 @@ -0,0 +1,40 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.translate 3 2025-04-19T14:30:40.368308 "Tomo man-pages" +.SH NAME +Text.translate \- Takes a table mapping target texts to their replacements and performs all the replacements in the table on the whole text. At each position, the first matching replacement is applied and the matching moves on to *after* the replacement text, so replacement text is not recursively modified. See [`replace()`](#replace) for more information about replacement behavior. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.translate : func(translations: {Text=Text} -> Text)" +.fi + +.SH DESCRIPTION +Takes a table mapping target texts to their replacements and performs all the replacements in the table on the whole text. At each position, the first matching replacement is applied and the matching moves on to *after* the replacement text, so replacement text is not recursively modified. See [`replace()`](#replace) for more information about replacement behavior. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +translations {Text=Text} A table mapping from target text to its replacement. - +.TE +.SH RETURN +The text with all occurrences of the targets replaced with their corresponding replacement text. + +.SH EXAMPLES +.EX +>> "A & an amperand".translate({ +"&" = "&", +"<" = "<", +">" = ">", +\&'"" = """, +"'" = "'", +} += "A <tag> & an ampersand" +.EE diff --git a/man/man3/tomo-Text.trim.3 b/man/man3/tomo-Text.trim.3 new file mode 100644 index 00000000..2c927630 --- /dev/null +++ b/man/man3/tomo-Text.trim.3 @@ -0,0 +1,43 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.trim 3 2025-04-19T14:30:40.368347 "Tomo man-pages" +.SH NAME +Text.trim \- Trims the given characters (grapheme clusters) from the left and/or right side of the text. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.trim : func(text: Text, to_trim: Text = " $\\t\\r\\n", left: Bool = yes, right: Bool = yes -> Text)" +.fi + +.SH DESCRIPTION +Trims the given characters (grapheme clusters) from the left and/or right side of the text. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to be trimmed. - +to_trim Text The characters to remove from the left/right of the text. " $\\t\\r\\n" +left Bool Whether or not to trim from the front of the text. yes +right Bool Whether or not to trim from the back of the text. yes +.TE +.SH RETURN +The text without the trim characters at either end. + +.SH EXAMPLES +.EX +>> " x y z \\n".trim() += "x y z" + +>> "one,".trim(",") += "one" + +>> " xyz ".trim(right=no) += "xyz " +.EE diff --git a/man/man3/tomo-Text.upper.3 b/man/man3/tomo-Text.upper.3 new file mode 100644 index 00000000..b6602765 --- /dev/null +++ b/man/man3/tomo-Text.upper.3 @@ -0,0 +1,39 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.upper 3 2025-04-19T14:30:40.368388 "Tomo man-pages" +.SH NAME +Text.upper \- Converts all characters in the text to uppercase. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.upper : func(text: Text, language: Text = "C" -> Text)" +.fi + +.SH DESCRIPTION +Converts all characters in the text to uppercase. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to be converted to uppercase. - +language Text The ISO 639 language code for which casing rules to use. "C" +.TE +.SH RETURN +The uppercase version of the text. + +.SH EXAMPLES +.EX +>> "amélie".upper() += "AMÉLIE" + +# In Turkish, uppercase "i" is "İ" +>> "i".upper(language="tr_TR") += "İ" +.EE diff --git a/man/man3/tomo-Text.utf32_codepoints.3 b/man/man3/tomo-Text.utf32_codepoints.3 new file mode 100644 index 00000000..2ceb620b --- /dev/null +++ b/man/man3/tomo-Text.utf32_codepoints.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.utf32_codepoints 3 2025-04-19T14:30:40.368427 "Tomo man-pages" +.SH NAME +Text.utf32_codepoints \- Returns a list of Unicode code points for UTF32 encoding of the text. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.utf32_codepoints : func(text: Text -> [Int32])" +.fi + +.SH DESCRIPTION +Returns a list of Unicode code points for UTF32 encoding of the text. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text from which to extract Unicode code points. - +.TE +.SH RETURN +A list of 32-bit integer Unicode code points (`[Int32]`). + +.SH EXAMPLES +.EX +>> "Amélie".utf32_codepoints() += [65, 109, 233, 108, 105, 101] +.EE diff --git a/man/man3/tomo-Text.width.3 b/man/man3/tomo-Text.width.3 new file mode 100644 index 00000000..46b29fee --- /dev/null +++ b/man/man3/tomo-Text.width.3 @@ -0,0 +1,39 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.width 3 2025-04-19T14:30:40.368465 "Tomo man-pages" +.SH NAME +Text.width \- Returns the display width of the text as seen in a terminal with appropriate font rendering. This is usually the same as the text's `.length`, but there are some characters like emojis that render wider than 1 cell. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.width : func(text: Text -> Int)" +.fi + +.SH DESCRIPTION +Returns the display width of the text as seen in a terminal with appropriate font rendering. This is usually the same as the text's `.length`, but there are some characters like emojis that render wider than 1 cell. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text whose length you want. - +.TE +.SH RETURN +An integer representing the display width of the text. + +.SH NOTES +This will not always be exactly accurate when your terminal's font rendering can't handle some unicode displaying correctly. + +.SH EXAMPLES +.EX +>> "Amélie".width() += 6 +>> "🤠".width() += 2 +.EE diff --git a/man/man3/tomo-Text.without_prefix.3 b/man/man3/tomo-Text.without_prefix.3 new file mode 100644 index 00000000..1ed3f644 --- /dev/null +++ b/man/man3/tomo-Text.without_prefix.3 @@ -0,0 +1,37 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.without_prefix 3 2025-04-19T14:30:40.368531 "Tomo man-pages" +.SH NAME +Text.without_prefix \- Returns the text with a given prefix removed (if present). + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.without_prefix : func(text: Text, prefix: Text -> Text)" +.fi + +.SH DESCRIPTION +Returns the text with a given prefix removed (if present). + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to remove the prefix from. - +prefix Text The prefix to remove. - +.TE +.SH RETURN +A text without the given prefix (if present) or the unmodified text if the prefix is not present. + +.SH EXAMPLES +.EX +>> "foo:baz".without_prefix("foo:") += "baz" +>> "qux".without_prefix("foo:") += "qux" +.EE diff --git a/man/man3/tomo-Text.without_suffix.3 b/man/man3/tomo-Text.without_suffix.3 new file mode 100644 index 00000000..710e7852 --- /dev/null +++ b/man/man3/tomo-Text.without_suffix.3 @@ -0,0 +1,37 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH Text.without_suffix 3 2025-04-19T14:30:40.368570 "Tomo man-pages" +.SH NAME +Text.without_suffix \- Returns the text with a given suffix removed (if present). + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "Text.without_suffix : func(text: Text, suffix: Text -> Text)" +.fi + +.SH DESCRIPTION +Returns the text with a given suffix removed (if present). + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to remove the suffix from. - +suffix Text The suffix to remove. - +.TE +.SH RETURN +A text without the given suffix (if present) or the unmodified text if the suffix is not present. + +.SH EXAMPLES +.EX +>> "baz.foo".without_suffix(".foo") += "baz" +>> "qux".without_suffix(".foo") += "qux" +.EE diff --git a/man/man3/tomo-USE_COLOR.3 b/man/man3/tomo-USE_COLOR.3 new file mode 100644 index 00000000..fdad34a1 --- /dev/null +++ b/man/man3/tomo-USE_COLOR.3 @@ -0,0 +1,18 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH USE_COLOR 3 2025-04-19T14:30:40.360080 "Tomo man-pages" +.SH NAME +USE_COLOR \- Whether or not the console prefers ANSI color escape sequences in the output. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI 'USE_COLOR : Bool' +.fi + +.SH DESCRIPTION +Whether or not the console prefers ANSI color escape sequences in the output. + diff --git a/man/man3/tomo-ask.3 b/man/man3/tomo-ask.3 new file mode 100644 index 00000000..f90d09ce --- /dev/null +++ b/man/man3/tomo-ask.3 @@ -0,0 +1,39 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH ask 3 2025-04-19T14:30:40.359728 "Tomo man-pages" +.SH NAME +ask \- Gets a line of user input text with a prompt. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "ask : func(prompt: Text, bold: Bool = yes, force_tty: Bool = yes -> Text?)" +.fi + +.SH DESCRIPTION +Gets a line of user input text with a prompt. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +prompt Text The text to print as a prompt before getting the input. - +bold Bool Whether or not to print make the prompt appear bold on a console. yes +force_tty Bool Whether or not to force the use of /dev/tty. yes +.TE +.SH RETURN +A line of user input text without a trailing newline, or empty text if something went wrong (e.g. the user hit `Ctrl-D`). + +.SH NOTES +When a program is receiving input from a pipe or writing its output to a pipe, this flag (which is enabled by default) forces the program to write the prompt to `/dev/tty` and read the input from `/dev/tty`, which circumvents the pipe. This means that `foo | ./tomo your-program | baz` will still show a visible prompt and read user input, despite the pipes. Setting this flag to `no` will mean that the prompt is written to `stdout` and input is read from `stdin`, even if those are pipes. + +.SH EXAMPLES +.EX +>> ask("What's your name? ") += "Arthur Dent" +.EE diff --git a/man/man3/tomo-exit.3 b/man/man3/tomo-exit.3 new file mode 100644 index 00000000..e285bd36 --- /dev/null +++ b/man/man3/tomo-exit.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH exit 3 2025-04-19T14:30:40.359796 "Tomo man-pages" +.SH NAME +exit \- Exits the program with a given status and optionally prints a message. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "exit : func(message: Text? = !Text, status: Int32 = Int32(1) -> Void)" +.fi + +.SH DESCRIPTION +Exits the program with a given status and optionally prints a message. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +message Text? If nonempty, this message will be printed (with a newline) before exiting. !Text +status Int32 The status code that the program with exit with. Int32(1) +.TE +.SH RETURN +This function never returns. + +.SH EXAMPLES +.EX +exit(status=1, "Goodbye forever!") +.EE diff --git a/man/man3/tomo-fail.3 b/man/man3/tomo-fail.3 new file mode 100644 index 00000000..a77ba9fa --- /dev/null +++ b/man/man3/tomo-fail.3 @@ -0,0 +1,33 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH fail 3 2025-04-19T14:30:40.360045 "Tomo man-pages" +.SH NAME +fail \- Prints a message to the console, aborts the program, and prints a stack trace. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "fail : func(message: Text -> Abort)" +.fi + +.SH DESCRIPTION +Prints a message to the console, aborts the program, and prints a stack trace. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +message Text The error message to print. - +.TE +.SH RETURN +Nothing, aborts the program. + +.SH EXAMPLES +.EX +fail("Oh no!") +.EE diff --git a/man/man3/tomo-getenv.3 b/man/man3/tomo-getenv.3 new file mode 100644 index 00000000..50bec810 --- /dev/null +++ b/man/man3/tomo-getenv.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH getenv 3 2025-04-19T14:30:40.359840 "Tomo man-pages" +.SH NAME +getenv \- Gets an environment variable. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "getenv : func(name: Text -> Text?)" +.fi + +.SH DESCRIPTION +Gets an environment variable. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +name Text The name of the environment variable to get. - +.TE +.SH RETURN +If set, the environment variable's value, otherwise, `none`. + +.SH EXAMPLES +.EX +>> getenv("TERM") += "xterm-256color"? +.EE diff --git a/man/man3/tomo-print.3 b/man/man3/tomo-print.3 new file mode 100644 index 00000000..52c55e91 --- /dev/null +++ b/man/man3/tomo-print.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH print 3 2025-04-19T14:30:40.359894 "Tomo man-pages" +.SH NAME +print \- Prints a message to the console (alias for [`say`](#say)). + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "print : func(text: Text, newline: Bool = yes -> Void)" +.fi + +.SH DESCRIPTION +Prints a message to the console (alias for [`say`](#say)). + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to print. - +newline Bool Whether or not to print a newline after the text. yes +.TE +.SH RETURN +Nothing. + +.SH EXAMPLES +.EX +print("Hello ", newline=no) +print("world!") +.EE diff --git a/man/man3/tomo-say.3 b/man/man3/tomo-say.3 new file mode 100644 index 00000000..f14db1f7 --- /dev/null +++ b/man/man3/tomo-say.3 @@ -0,0 +1,35 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH say 3 2025-04-19T14:30:40.359935 "Tomo man-pages" +.SH NAME +say \- Prints a message to the console. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "say : func(text: Text, newline: Bool = yes -> Void)" +.fi + +.SH DESCRIPTION +Prints a message to the console. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +text Text The text to print. - +newline Bool Whether or not to print a newline after the text. yes +.TE +.SH RETURN +Nothing. + +.SH EXAMPLES +.EX +say("Hello ", newline=no) +say("world!") +.EE diff --git a/man/man3/tomo-setenv.3 b/man/man3/tomo-setenv.3 new file mode 100644 index 00000000..0bd8baba --- /dev/null +++ b/man/man3/tomo-setenv.3 @@ -0,0 +1,34 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH setenv 3 2025-04-19T14:30:40.359972 "Tomo man-pages" +.SH NAME +setenv \- Sets an environment variable. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "setenv : func(name: Text, value: Text -> Void)" +.fi + +.SH DESCRIPTION +Sets an environment variable. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +name Text The name of the environment variable to set. - +value Text The new value of the environment variable. - +.TE +.SH RETURN +Nothing. + +.SH EXAMPLES +.EX +setenv("FOOBAR", "xyz") +.EE diff --git a/man/man3/tomo-sleep.3 b/man/man3/tomo-sleep.3 new file mode 100644 index 00000000..16d24e2d --- /dev/null +++ b/man/man3/tomo-sleep.3 @@ -0,0 +1,33 @@ +'\" t +.\" Copyright (c) 2025 Bruce Hill +.\" All rights reserved. +.\" +.TH sleep 3 2025-04-19T14:30:40.360009 "Tomo man-pages" +.SH NAME +sleep \- Pause execution for a given number of seconds. + +.SH LIBRARY +Tomo Standard Library +.SH SYNOPSIS +.nf +.BI "sleep : func(seconds: Num -> Void)" +.fi + +.SH DESCRIPTION +Pause execution for a given number of seconds. + + +.TS +allbox; +lb lb lbx lb +l l l l. +Name Type Description Default +seconds Num How many seconds to sleep for. - +.TE +.SH RETURN +Nothing. + +.SH EXAMPLES +.EX +sleep(1.5) +.EE diff --git a/scripts/api_gen.py b/scripts/api_gen.py new file mode 100755 index 00000000..bc264e10 --- /dev/null +++ b/scripts/api_gen.py @@ -0,0 +1,80 @@ +#!/bin/env python3 + +# This script converts API YAML files into markdown documentation +# and prints it to standard out. + +import yaml +import re + +def arg_signature(name, arg): + sig = name + if "type" in arg: + sig = sig + ": " + arg["type"] + if "default" in arg: + sig = sig + " = " + arg["default"] + return sig + +def get_signature(name, info): + if "type" in info: + return name + " : " + info["type"] + sig = name + " : func(" + if info["args"]: + sig += ", ".join(arg_signature(name,arg) for name,arg in info["args"].items()) + sig += " -> " + info["return"].get("type", "Void") + else: + sig += "-> " + info["return"].get("type", "Void") + sig += ")" + return sig + +def print_method(name, info): + print(f"## {name}") + print(f"\n```tomo\n{get_signature(name, info)}\n```\n") + if "description" in info: + print(info["description"]) + if "note" in info: + print(info["note"]) + if "errors" in info: + print(info["errors"]) + + if "args" in info and info["args"]: + print("Argument | Type | Description | Default") + print("---------|------|-------------|---------") + for arg,arg_info in info["args"].items(): + default = '**Default:** `'+arg_info['default']+'`' if 'default' in arg_info else '' + description = arg_info['description'].replace('\n', ' ') + print(f"{arg} | `{arg_info.get('type', '')}` | {description} | {default}") + #print(f"- **{arg}:** {arg_info['description']}") + + if "return" in info: + print(f"\n**Return:** {info['return'].get('description', 'Nothing.')}") + + if "example" in info: + print(f"\n**Example:**\n```tomo\n{info['example']}\n```") + +def convert_to_markdown(yaml_doc:str)->str: + data = yaml.safe_load(yaml_doc) + + print("# Builtins") + for name in sorted([k for k in data.keys() if "." not in k]): + print_method(name, data[name]) + + section = None + for name in sorted([k for k in data.keys() if "." in k]): + if section is None or not name.startswith(section + "."): + match = re.match(r"(\w+)\.", name) + section = match.group(1) + print(f"\n# {section}") + + print_method(name, data[name]) + +if __name__ == "__main__": + import sys + print("% API\n") + if len(sys.argv) > 1: + all_files = "" + for filename in sys.argv[1:]: + with open(filename, "r") as f: + all_files += f.read() + convert_to_markdown(all_files) + else: + convert_to_markdown(sys.stdin.read()) -- cgit v1.2.3