From efe59213a7705ac95f25d800c87a0e3fc7de6c22 Mon Sep 17 00:00:00 2001 From: Bzero Date: Sat, 14 Sep 2024 20:59:39 +0200 Subject: [PATCH 1/9] Add @examples decorator --- numbat/examples/inspect.rs | 2 +- numbat/src/decorator.rs | 21 +++++++ numbat/src/lib.rs | 2 + numbat/src/parser.rs | 85 +++++++++++++++++++++++++++ numbat/src/typechecker/environment.rs | 1 + numbat/src/typechecker/mod.rs | 1 + numbat/src/typed_ast.rs | 11 ++++ 7 files changed, 122 insertions(+), 1 deletion(-) diff --git a/numbat/examples/inspect.rs b/numbat/examples/inspect.rs index e61b37ac..989f12ed 100644 --- a/numbat/examples/inspect.rs +++ b/numbat/examples/inspect.rs @@ -41,7 +41,7 @@ and — where sensible — units allow for [binary prefixes](https://en.wikipedi } fn inspect_functions_in_module(ctx: &Context, module: String) { - for (fn_name, name, signature, description, url, code_source) in ctx.functions() { + for (fn_name, name, signature, description, url, examples, code_source) in ctx.functions() { let CodeSource::Module(module_path, _) = code_source else { unreachable!(); }; diff --git a/numbat/src/decorator.rs b/numbat/src/decorator.rs index a000dce7..f93758f2 100644 --- a/numbat/src/decorator.rs +++ b/numbat/src/decorator.rs @@ -8,6 +8,7 @@ pub enum Decorator { Url(String), Name(String), Description(String), + Example(String, Option), } pub fn name_and_aliases<'a>( @@ -89,6 +90,16 @@ pub fn description(decorators: &[Decorator]) -> Option { } } +pub fn examples(decorators: &[Decorator]) -> Vec<(String, Option)> { + let mut examples = Vec::new(); + for decorator in decorators { + if let Decorator::Example(example_code, example_description) = decorator { + examples.push((example_code.clone(), example_description.clone())); + } + } + return examples; +} + pub fn contains_aliases_with_prefixes(decorates: &[Decorator]) -> bool { for decorator in decorates { if let Decorator::Aliases(aliases) = decorator { @@ -110,3 +121,13 @@ pub fn contains_aliases(decorators: &[Decorator]) -> bool { false } + +pub fn contains_examples(decorators: &[Decorator]) -> bool { + for decorator in decorators { + if let Decorator::Example(_, _) = decorator { + return true; + } + } + + false +} diff --git a/numbat/src/lib.rs b/numbat/src/lib.rs index a400aaba..1f1ac4a3 100644 --- a/numbat/src/lib.rs +++ b/numbat/src/lib.rs @@ -168,6 +168,7 @@ impl Context { String, Option, Option, + Vec<(String, Option)>, CodeSource, ), > + '_ { @@ -185,6 +186,7 @@ impl Context { .to_string(), meta.description.clone(), meta.url.clone(), + meta.examples.clone(), self.resolver .get_code_source(signature.definition_span.code_source_id), ) diff --git a/numbat/src/parser.rs b/numbat/src/parser.rs index f0f19837..e7567736 100644 --- a/numbat/src/parser.rs +++ b/numbat/src/parser.rs @@ -198,6 +198,9 @@ pub enum ParseErrorKind { #[error("Aliases cannot be used on functions.")] AliasUsedOnFunction, + #[error("Example decorators can only be used on functions.")] + ExampleUsedOnUnsuitableKind, + #[error("Numerical overflow in dimension exponent")] OverflowInDimensionExponent, @@ -456,6 +459,14 @@ impl Parser { span: self.peek(tokens).span, }); } + + if decorator::contains_examples(&self.decorator_stack) { + return Err(ParseError { + kind: ParseErrorKind::ExampleUsedOnUnsuitableKind, + span: self.peek(tokens).span, + }); + } + std::mem::swap(&mut decorators, &mut self.decorator_stack); } @@ -735,6 +746,55 @@ impl Parser { }); } } + "example" => { + if self.match_exact(tokens, TokenKind::LeftParen).is_some() { + if let Some(token_code) = self.match_exact(tokens, TokenKind::StringFixed) { + if self.match_exact(tokens, TokenKind::Comma).is_some() { + //Code and description + if let Some(token_description) = + self.match_exact(tokens, TokenKind::StringFixed) + { + if self.match_exact(tokens, TokenKind::RightParen).is_none() { + return Err(ParseError::new( + ParseErrorKind::MissingClosingParen, + self.peek(tokens).span, + )); + } + + Decorator::Example( + strip_and_escape(&token_code.lexeme), + Some(strip_and_escape(&token_description.lexeme)), + ) + } else { + return Err(ParseError { + kind: ParseErrorKind::ExpectedString, + span: self.peek(tokens).span, + }); + } + } else { + //Code but no description + if self.match_exact(tokens, TokenKind::RightParen).is_none() { + return Err(ParseError::new( + ParseErrorKind::MissingClosingParen, + self.peek(tokens).span, + )); + } + + Decorator::Example(strip_and_escape(&token_code.lexeme), None) + } + } else { + return Err(ParseError { + kind: ParseErrorKind::ExpectedString, + span: self.peek(tokens).span, + }); + } + } else { + return Err(ParseError { + kind: ParseErrorKind::ExpectedLeftParenAfterDecorator, + span: self.peek(tokens).span, + }); + } + } _ => { return Err(ParseError { kind: ParseErrorKind::UnknownDecorator, @@ -769,6 +829,13 @@ impl Parser { let unit_name = identifier.lexeme.to_owned(); + if decorator::contains_examples(&self.decorator_stack) { + return Err(ParseError { + kind: ParseErrorKind::ExampleUsedOnUnsuitableKind, + span: self.peek(tokens).span, + }); + } + let mut decorators = vec![]; std::mem::swap(&mut decorators, &mut self.decorator_stack); @@ -2795,6 +2862,24 @@ mod tests { }, ); + parse_as( + &["@name(\"Some function\") @example(\"some_function(2)\", \"Use this function:\") @example(\"let some_var = some_function(0)\") fn some_function(x) = 1"], + Statement::DefineFunction { + function_name_span: Span::dummy(), + function_name: "some_function".into(), + type_parameters: vec![], + parameters: vec![(Span::dummy(), "x".into(), None)], + body: Some(scalar!(1.0)), + local_variables: vec![], + return_type_annotation: None, + decorators: vec![ + decorator::Decorator::Name("Some function".into()), + decorator::Decorator::Example("some_function(2)".into(), Some("Use this function:".into())), + decorator::Decorator::Example("let some_var = some_function(0)".into(), None), + ], + }, + ); + parse_as( &["fn double_kef(x) = y where y = x * 2"], Statement::DefineFunction { diff --git a/numbat/src/typechecker/environment.rs b/numbat/src/typechecker/environment.rs index d161dd0c..fe367545 100644 --- a/numbat/src/typechecker/environment.rs +++ b/numbat/src/typechecker/environment.rs @@ -68,6 +68,7 @@ pub struct FunctionMetadata { pub name: Option, pub url: Option, pub description: Option, + pub examples: Vec<(String, Option)>, } #[derive(Clone, Debug)] diff --git a/numbat/src/typechecker/mod.rs b/numbat/src/typechecker/mod.rs index eb64009b..7a296967 100644 --- a/numbat/src/typechecker/mod.rs +++ b/numbat/src/typechecker/mod.rs @@ -1420,6 +1420,7 @@ impl TypeChecker { name: crate::decorator::name(decorators), url: crate::decorator::url(decorators), description: crate::decorator::description(decorators), + examples: crate::decorator::examples(decorators), }, ); diff --git a/numbat/src/typed_ast.rs b/numbat/src/typed_ast.rs index 331bbb7c..2538dae2 100644 --- a/numbat/src/typed_ast.rs +++ b/numbat/src/typed_ast.rs @@ -857,6 +857,17 @@ fn decorator_markup(decorators: &Vec) -> Markup { + m::string(description) + m::operator(")") } + Decorator::Example(example_code, example_description) => { + m::decorator("@example") + + m::operator("(") + + m::string(example_code) + + if let Some(example_description) = example_description { + m::operator(", ") + m::string(example_description) + } else { + m::empty() + } + + m::operator(")") + } } + m::nl(); } From 0210b9cc5295eeff24ef23b2d9ee20700acd9d74 Mon Sep 17 00:00:00 2001 From: Bzero Date: Sun, 15 Sep 2024 14:31:08 +0200 Subject: [PATCH 2/9] Automatically add examples to the documentation --- Cargo.lock | 1 + numbat/Cargo.toml | 1 + numbat/examples/inspect.rs | 138 ++++++++++++++++++++++++++++++++----- numbat/src/markup.rs | 4 ++ numbat/src/resolver.rs | 2 +- 5 files changed, 128 insertions(+), 18 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 9e1e170e..7c78a4ea 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1089,6 +1089,7 @@ dependencies = [ "num-traits", "numbat-exchange-rates", "once_cell", + "percent-encoding", "plotly", "pretty_dtoa", "rand", diff --git a/numbat/Cargo.toml b/numbat/Cargo.toml index 69420a40..b527c5fb 100644 --- a/numbat/Cargo.toml +++ b/numbat/Cargo.toml @@ -49,6 +49,7 @@ glob = "0.3" insta = "1.34.0" once_cell = "1.19.0" criterion = { version = "0.5", features = ["html_reports"] } +percent-encoding = "2.3.1" [[bench]] name = "prelude" diff --git a/numbat/examples/inspect.rs b/numbat/examples/inspect.rs index 989f12ed..74f65c67 100644 --- a/numbat/examples/inspect.rs +++ b/numbat/examples/inspect.rs @@ -1,5 +1,10 @@ use itertools::Itertools; -use numbat::{module_importer::FileSystemImporter, resolver::CodeSource, Context}; +use numbat::markup::plain_text_format; +use numbat::module_importer::FileSystemImporter; +use numbat::pretty_print::PrettyPrint; +use numbat::resolver::CodeSource; +use numbat::Context; +use percent_encoding; use std::path::Path; const AUTO_GENERATED_HINT: &str = ""; @@ -57,19 +62,7 @@ fn inspect_functions_in_module(ctx: &Context, module: String) { } if let Some(ref description_raw) = description { - let description_raw = description_raw.trim().to_string(); - - // Replace $..$ with \\( .. \\) for mdbook. - let mut description = String::new(); - for (i, part) in description_raw.split('$').enumerate() { - if i % 2 == 0 { - description.push_str(part); - } else { - description.push_str("\\\\( "); - description.push_str(part); - description.push_str(" \\\\)"); - } - } + let description = replace_equation_delimiters(description_raw.trim().to_string()); if description.ends_with('.') { println!("{description}"); @@ -86,15 +79,126 @@ fn inspect_functions_in_module(ctx: &Context, module: String) { println!("{signature}"); println!("```"); println!(); + + if !examples.is_empty() { + println!("
"); + println!("Examples"); + println!(); + } + + for (example_code, example_description) in examples { + let mut example_ctx = prepare_context(); + let _result = example_ctx + .interpret("use prelude", CodeSource::Internal) + .unwrap(); + + let extra_import = if !example_ctx + .resolver() + .imported_modules + .contains(&module_path) + { + format!("use {}\n", module) + } else { + "".into() + }; + let _result = example_ctx + .interpret(&extra_import, CodeSource::Internal) + .unwrap(); + + if let Ok((statements, results)) = + example_ctx.interpret(&example_code, CodeSource::Internal) + { + //Format the example input + let example_input = format!(">>> {}", example_code); + + //Encode the example url + let url_code = extra_import + &example_code; + let example_url = format!( + "https://numbat.dev/?q={}", + percent_encoding::utf8_percent_encode( + &url_code, + percent_encoding::NON_ALPHANUMERIC + ) + ); + + //Assemble the example output + let mut example_output = String::new(); + example_output += "\n"; + + for statement in &statements { + example_output += &plain_text_format(&statement.pretty_print(), true); + example_output += "\n\n"; + } + + let result_markup = results.to_markup( + statements.last(), + &example_ctx.dimension_registry(), + true, + true, + ); + example_output += &plain_text_format(&result_markup, false); + + if results.is_value() { + example_output += "\n"; + } + + //Print the example + if let Some(example_description) = example_description { + println!( + "* {}\n\n Run this example", + replace_equation_delimiters(example_description), + example_url + ); + } else { + println!( + "* Run this example\n", + example_url + ); + } + + println!(" ```nbt"); + for l in example_input.lines() { + println!(" {}", l); + } + for l in example_output.lines() { + println!(" {}", l); + } + println!(" ```"); + } else { + eprintln!( + "Warning: Example \"{example_code}\" of function {fn_name} did not run successfully." + ); + } + } + println!("
"); + println!(); } } -fn main() { - let module_path = Path::new(&std::env::var_os("CARGO_MANIFEST_DIR").unwrap()).join("modules"); +// Replace $..$ with \\( .. \\) for mdbook. +fn replace_equation_delimiters(text_in: String) -> String { + let mut text_out = String::new(); + for (i, part) in text_in.split('$').enumerate() { + if i % 2 == 0 { + text_out.push_str(part); + } else { + text_out.push_str("\\\\( "); + text_out.push_str(part); + text_out.push_str(" \\\\)"); + } + } + return text_out; +} +fn prepare_context() -> Context { + let module_path = Path::new(&std::env::var_os("CARGO_MANIFEST_DIR").unwrap()).join("modules"); let mut importer = FileSystemImporter::default(); importer.add_path(module_path); - let mut ctx = Context::new(importer); + return Context::new(importer); +} + +fn main() { + let mut ctx = prepare_context(); let _result = ctx.interpret("use all", CodeSource::Internal).unwrap(); let mut args = std::env::args(); diff --git a/numbat/src/markup.rs b/numbat/src/markup.rs index 850e3908..f06b5bdc 100644 --- a/numbat/src/markup.rs +++ b/numbat/src/markup.rs @@ -209,3 +209,7 @@ impl Formatter for PlainTextFormatter { text.clone() } } + +pub fn plain_text_format(m: &Markup, indent: bool) -> String { + PlainTextFormatter {}.format(m, indent) +} diff --git a/numbat/src/resolver.rs b/numbat/src/resolver.rs index 5f653fd6..6a626f08 100644 --- a/numbat/src/resolver.rs +++ b/numbat/src/resolver.rs @@ -49,7 +49,7 @@ pub struct Resolver { pub files: SimpleFiles, text_code_source_count: usize, internal_code_source_count: usize, - imported_modules: Vec, + pub imported_modules: Vec, codesources: HashMap, } From 04e1772221a027a9622495818616cd9c5fb41d44 Mon Sep 17 00:00:00 2001 From: Bzero Date: Sun, 15 Sep 2024 14:46:38 +0000 Subject: [PATCH 3/9] Expand documentation by adding examples --- book/build.py | 4 + book/src/list-functions-datetime.md | 230 ++++++ book/src/list-functions-lists.md | 350 +++++++++ book/src/list-functions-math.md | 683 +++++++++++++++++- book/src/list-functions-other.md | 343 ++++++++- book/src/list-functions-strings.md | 252 ++++++- numbat/modules/chemistry/elements.nbt | 4 +- numbat/modules/core/functions.nbt | 29 +- numbat/modules/core/lists.nbt | 23 + numbat/modules/core/numbers.nbt | 6 + numbat/modules/core/quantities.nbt | 2 + numbat/modules/core/strings.nbt | 28 +- numbat/modules/datetime/functions.nbt | 15 + numbat/modules/datetime/human.nbt | 1 + numbat/modules/extra/algebra.nbt | 1 + numbat/modules/extra/color.nbt | 13 +- numbat/modules/math/geometry.nbt | 2 + numbat/modules/math/number_theory.nbt | 2 + numbat/modules/math/statistics.nbt | 12 +- numbat/modules/math/transcendental.nbt | 5 + numbat/modules/numerics/diff.nbt | 1 + numbat/modules/numerics/fixed_point.nbt | 1 + numbat/modules/numerics/solve.nbt | 2 + .../physics/temperature_conversion.nbt | 4 + numbat/modules/units/mixed.nbt | 4 + 25 files changed, 1981 insertions(+), 36 deletions(-) diff --git a/book/build.py b/book/build.py index 61ab370f..7a7c1e1f 100644 --- a/book/build.py +++ b/book/build.py @@ -1,6 +1,7 @@ import subprocess from pathlib import Path import urllib.parse +import os SCRIPT_DIR = Path(__file__).parent.resolve() @@ -119,6 +120,8 @@ def list_of_functions(file_name, document): print( f"Generating list of functions for module '{module}'...", flush=True ) + env = os.environ.copy() + env["TZ"] = "UTC" subprocess.run( [ "cargo", @@ -132,6 +135,7 @@ def list_of_functions(file_name, document): ], stdout=f, text=True, + env=env, ) diff --git a/book/src/list-functions-datetime.md b/book/src/list-functions-datetime.md index ede5544f..d43ad85b 100644 --- a/book/src/list-functions-datetime.md +++ b/book/src/list-functions-datetime.md @@ -11,6 +11,8 @@ Returns the current date and time. fn now() -> DateTime ``` + + ### `datetime` Parses a string (date and time) into a `DateTime` object. See [here](./date-and-time.md#date-time-formats) for an overview of the supported formats. @@ -18,6 +20,41 @@ Parses a string (date and time) into a `DateTime` object. See [here](./date-and- fn datetime(input: String) -> DateTime ``` +
+Examples + +* Run this example + + ```nbt + >>> datetime("2022-07-20T21:52+0200") + + datetime("2022-07-20T21:52+0200") + + = 2022-07-20 19:52:00 UTC [DateTime] + + ``` +* Run this example + + ```nbt + >>> datetime("2022-07-20 21:52 Europe/Berlin") + + datetime("2022-07-20 21:52 Europe/Berlin") + + = 2022-07-20 21:52:00 CEST (UTC +02), Europe/Berlin [DateTime] + + ``` +* Run this example + + ```nbt + >>> datetime("2022/07/20 09:52 PM +0200") + + datetime("2022/07/20 09:52 PM +0200") + + = 2022-07-20 21:52:00 (UTC +02) [DateTime] + + ``` +
+ ### `format_datetime` Formats a `DateTime` object as a string. @@ -25,6 +62,21 @@ Formats a `DateTime` object as a string. fn format_datetime(format: String, input: DateTime) -> String ``` +
+Examples + +* Run this example + + ```nbt + >>> format_datetime("This is a date in %B in the year %Y.", datetime("2022-07-20 21:52 +0200")) + + format_datetime("This is a date in %B in the year %Y.", datetime("2022-07-20 21:52 +0200")) + + = "This is a date in July in the year 2022." [String] + + ``` +
+ ### `get_local_timezone` Returns the users local timezone. @@ -32,6 +84,21 @@ Returns the users local timezone. fn get_local_timezone() -> String ``` +
+Examples + +* Run this example + + ```nbt + >>> get_local_timezone() + + get_local_timezone() + + = "UTC" [String] + + ``` +
+ ### `tz` Returns a timezone conversion function, typically used with the conversion operator. @@ -39,6 +106,31 @@ Returns a timezone conversion function, typically used with the conversion opera fn tz(tz: String) -> Fn[(DateTime) -> DateTime] ``` +
+Examples + +* Run this example + + ```nbt + >>> datetime("2022-07-20 21:52 +0200") -> tz("Europe/Amsterdam") + + tz("Europe/Amsterdam")(datetime("2022-07-20 21:52 +0200")) + + = 2022-07-20 21:52:00 CEST (UTC +02), Europe/Amsterdam [DateTime] + + ``` +* Run this example + + ```nbt + >>> datetime("2022-07-20 21:52 +0200") -> tz("Asia/Taipei") + + tz("Asia/Taipei")(datetime("2022-07-20 21:52 +0200")) + + = 2022-07-21 03:52:00 CST (UTC +08), Asia/Taipei [DateTime] + + ``` +
+ ### `unixtime` Converts a `DateTime` to a UNIX timestamp. Can be used on the right hand side of a conversion operator: `now() -> unixtime`. @@ -46,6 +138,21 @@ Converts a `DateTime` to a UNIX timestamp. Can be used on the right hand side of fn unixtime(input: DateTime) -> Scalar ``` +
+Examples + +* Run this example + + ```nbt + >>> datetime("2022-07-20 21:52 +0200") -> unixtime + + unixtime(datetime("2022-07-20 21:52 +0200")) + + = 1_658_346_720 + + ``` +
+ ### `from_unixtime` Converts a UNIX timestamp to a `DateTime` object. @@ -53,6 +160,21 @@ Converts a UNIX timestamp to a `DateTime` object. fn from_unixtime(input: Scalar) -> DateTime ``` +
+Examples + +* Run this example + + ```nbt + >>> from_unixtime(2^31) + + from_unixtime(2^31) + + = 2038-01-19 03:14:08 UTC [DateTime] + + ``` +
+ ### `today` Returns the current date at midnight (in the local time). @@ -60,6 +182,8 @@ Returns the current date at midnight (in the local time). fn today() -> DateTime ``` + + ### `date` Parses a string (only date) into a `DateTime` object. @@ -67,6 +191,21 @@ Parses a string (only date) into a `DateTime` object. fn date(input: String) -> DateTime ``` +
+Examples + +* Run this example + + ```nbt + >>> date("2022-07-20") + + date("2022-07-20") + + = 2022-07-20 00:00:00 UTC [DateTime] + + ``` +
+ ### `time` Parses a string (time only) into a `DateTime` object. @@ -74,6 +213,21 @@ Parses a string (time only) into a `DateTime` object. fn time(input: String) -> DateTime ``` +
+Examples + +* Run this example + + ```nbt + >>> time("21:52") + + time("21:52") + + = 2024-09-15 21:52:00 UTC [DateTime] + + ``` +
+ ### `calendar_add` Adds the given time span to a `DateTime`. This uses leap-year and DST-aware calendar arithmetic with variable-length days, months, and years. @@ -81,6 +235,21 @@ Adds the given time span to a `DateTime`. This uses leap-year and DST-aware cale fn calendar_add(dt: DateTime, span: Time) -> DateTime ``` +
+Examples + +* Run this example + + ```nbt + >>> calendar_add(datetime("2022-07-20 21:52 +0200"), 2 years) + + calendar_add(datetime("2022-07-20 21:52 +0200"), 2 year) + + = 2024-07-20 21:52:00 (UTC +02) [DateTime] + + ``` +
+ ### `calendar_sub` Subtract the given time span from a `DateTime`. This uses leap-year and DST-aware calendar arithmetic with variable-length days, months, and years. @@ -88,6 +257,21 @@ Subtract the given time span from a `DateTime`. This uses leap-year and DST-awar fn calendar_sub(dt: DateTime, span: Time) -> DateTime ``` +
+Examples + +* Run this example + + ```nbt + >>> calendar_sub(datetime("2022-07-20 21:52 +0200"), 3 years) + + calendar_sub(datetime("2022-07-20 21:52 +0200"), 3 year) + + = 2019-07-20 21:52:00 (UTC +02) [DateTime] + + ``` +
+ ### `weekday` Get the day of the week from a given `DateTime`. @@ -95,6 +279,21 @@ Get the day of the week from a given `DateTime`. fn weekday(dt: DateTime) -> String ``` +
+Examples + +* Run this example + + ```nbt + >>> weekday(datetime("2022-07-20 21:52 +0200")) + + weekday(datetime("2022-07-20 21:52 +0200")) + + = "Wednesday" [String] + + ``` +
+ ### `julian_date` (Julian date) Convert a `DateTime` to a Julian date, the number of days since the origin of the Julian date system (noon on November 24, 4714 BC in the proleptic Gregorian calendar). More information [here](https://en.wikipedia.org/wiki/Julian_day). @@ -103,6 +302,21 @@ More information [here](https://en.wikipedia.org/wiki/Julian_day). fn julian_date(dt: DateTime) -> Time ``` +
+Examples + +* Run this example + + ```nbt + >>> julian_date(datetime("2022-07-20 21:52 +0200")) + + julian_date(datetime("2022-07-20 21:52 +0200")) + + = 2.45978e+6 day [Time] + + ``` +
+ ### `human` (Human-readable time duration) Converts a time duration to a human-readable string in days, hours, minutes and seconds. More information [here](https://numbat.dev/doc/date-and-time.html). @@ -111,3 +325,19 @@ More information [here](https://numbat.dev/doc/date-and-time.html). fn human(time: Time) -> String ``` +
+Examples + +* How long is a microcentury? + + Run this example + ```nbt + >>> century/1e6 -> human + + human(century / 1_000_000) + + = "52 minutes + 35.692505184 seconds" [String] + + ``` +
+ diff --git a/book/src/list-functions-lists.md b/book/src/list-functions-lists.md index 10723fa0..7a9659b1 100644 --- a/book/src/list-functions-lists.md +++ b/book/src/list-functions-lists.md @@ -9,6 +9,21 @@ Get the length of a list. fn len(xs: List) -> Scalar ``` +
+Examples + +* Run this example + + ```nbt + >>> len([3, 2, 1]) + + len([3, 2, 1]) + + = 3 + + ``` +
+ ### `head` Get the first element of a list. Yields a runtime error if the list is empty. @@ -16,6 +31,21 @@ Get the first element of a list. Yields a runtime error if the list is empty. fn head(xs: List) -> A ``` +
+Examples + +* Run this example + + ```nbt + >>> head([3, 2, 1]) + + head([3, 2, 1]) + + = 3 + + ``` +
+ ### `tail` Get everything but the first element of a list. Yields a runtime error if the list is empty. @@ -23,6 +53,21 @@ Get everything but the first element of a list. Yields a runtime error if the li fn tail(xs: List) -> List ``` +
+Examples + +* Run this example + + ```nbt + >>> tail([3, 2, 1]) + + tail([3, 2, 1]) + + = [2, 1] [List] + + ``` +
+ ### `cons` Prepend an element to a list. @@ -30,6 +75,21 @@ Prepend an element to a list. fn cons(x: A, xs: List) -> List ``` +
+Examples + +* Run this example + + ```nbt + >>> cons(77, [3, 2, 1]) + + cons(77, [3, 2, 1]) + + = [77, 3, 2, 1] [List] + + ``` +
+ ### `cons_end` Append an element to the end of a list. @@ -37,6 +97,21 @@ Append an element to the end of a list. fn cons_end(x: A, xs: List) -> List ``` +
+Examples + +* Run this example + + ```nbt + >>> cons_end(77, [3, 2, 1]) + + cons_end(77, [3, 2, 1]) + + = [3, 2, 1, 77] [List] + + ``` +
+ ### `is_empty` Check if a list is empty. @@ -44,6 +119,31 @@ Check if a list is empty. fn is_empty(xs: List) -> Bool ``` +
+Examples + +* Run this example + + ```nbt + >>> is_empty([3, 2, 1]) + + is_empty([3, 2, 1]) + + = false [Bool] + + ``` +* Run this example + + ```nbt + >>> is_empty([]) + + is_empty([]) + + = true [Bool] + + ``` +
+ ### `concat` Concatenate two lists. @@ -51,6 +151,21 @@ Concatenate two lists. fn concat(xs1: List, xs2: List) -> List ``` +
+Examples + +* Run this example + + ```nbt + >>> concat([3, 2, 1], [10, 11]) + + concat([3, 2, 1], [10, 11]) + + = [3, 2, 1, 10, 11] [List] + + ``` +
+ ### `take` Get the first `n` elements of a list. @@ -58,6 +173,21 @@ Get the first `n` elements of a list. fn take(n: Scalar, xs: List) -> List ``` +
+Examples + +* Run this example + + ```nbt + >>> take(2, [3, 2, 1, 0]) + + take(2, [3, 2, 1, 0]) + + = [3, 2] [List] + + ``` +
+ ### `drop` Get everything but the first `n` elements of a list. @@ -65,6 +195,21 @@ Get everything but the first `n` elements of a list. fn drop(n: Scalar, xs: List) -> List ``` +
+Examples + +* Run this example + + ```nbt + >>> drop(2, [3, 2, 1, 0]) + + drop(2, [3, 2, 1, 0]) + + = [1, 0] [List] + + ``` +
+ ### `element_at` Get the element at index `i` in a list. @@ -72,6 +217,21 @@ Get the element at index `i` in a list. fn element_at(i: Scalar, xs: List) -> A ``` +
+Examples + +* Run this example + + ```nbt + >>> element_at(2, [3, 2, 1, 0]) + + element_at(2, [3, 2, 1, 0]) + + = 1 + + ``` +
+ ### `range` Generate a range of integer numbers from `start` to `end` (inclusive). @@ -79,6 +239,21 @@ Generate a range of integer numbers from `start` to `end` (inclusive). fn range(start: Scalar, end: Scalar) -> List ``` +
+Examples + +* Run this example + + ```nbt + >>> range(2, 12) + + range(2, 12) + + = [2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] [List] + + ``` +
+ ### `reverse` Reverse the order of a list. @@ -86,6 +261,21 @@ Reverse the order of a list. fn reverse(xs: List) -> List ``` +
+Examples + +* Run this example + + ```nbt + >>> reverse([3, 2, 1]) + + reverse([3, 2, 1]) + + = [1, 2, 3] [List] + + ``` +
+ ### `map` Generate a new list by applying a function to each element of the input list. @@ -93,6 +283,22 @@ Generate a new list by applying a function to each element of the input list. fn map(f: Fn[(A) -> B], xs: List) -> List ``` +
+Examples + +* Square all elements of a list. + + Run this example + ```nbt + >>> map(sqr, [3, 2, 1]) + + map(sqr, [3, 2, 1]) + + = [9, 4, 1] [List] + + ``` +
+ ### `filter` Filter a list by a predicate. @@ -100,6 +306,25 @@ Filter a list by a predicate. fn filter(p: Fn[(A) -> Bool], xs: List) -> List ``` +
+Examples + +* Filter all elements greater than \\( 1 \\). + + Run this example + ```nbt + >>> fn filter_fn(x) = x > 1 + filter(filter_fn, [3, 2, 1, 0]) + + fn filter_fn(x: Scalar) -> Bool = x > 1 + + filter(filter_fn, [3, 2, 1, 0]) + + = [3, 2] [List] + + ``` +
+ ### `foldl` Fold a function over a list. @@ -107,6 +332,22 @@ Fold a function over a list. fn foldl(f: Fn[(A, B) -> A], acc: A, xs: List) -> A ``` +
+Examples + +* Join a list of strings by folding. + + Run this example + ```nbt + >>> foldl(str_append, "", ["Num", "bat", "!"]) + + foldl(str_append, "", ["Num", "bat", "!"]) + + = "Numbat!" [String] + + ``` +
+ ### `sort_by_key` Sort a list of elements, using the given key function that maps the element to a quantity. @@ -114,6 +355,25 @@ Sort a list of elements, using the given key function that maps the element to a fn sort_by_key(key: Fn[(A) -> D], xs: List) -> List ``` +
+Examples + +* Sort by last digit. + + Run this example + ```nbt + >>> fn map_fn(x) = mod(x, 10) + sort_by_key(map_fn, [701, 313, 9999, 4]) + + fn map_fn(x: Scalar) -> Scalar = mod(x, 10) + + sort_by_key(map_fn, [701, 313, 9999, 4]) + + = [701, 313, 4, 9999] [List] + + ``` +
+ ### `sort` Sort a list of quantities. @@ -121,6 +381,21 @@ Sort a list of quantities. fn sort(xs: List) -> List ``` +
+Examples + +* Run this example + + ```nbt + >>> sort([3, 2, 7, 8, -4, 0, -5]) + + sort([3, 2, 7, 8, -4, 0, -5]) + + = [-5, -4, 0, 2, 3, 7, 8] [List] + + ``` +
+ ### `intersperse` Add an element between each pair of elements in a list. @@ -128,6 +403,21 @@ Add an element between each pair of elements in a list. fn intersperse(sep: A, xs: List) -> List ``` +
+Examples + +* Run this example + + ```nbt + >>> intersperse(0, [1, 1, 1, 1]) + + intersperse(0, [1, 1, 1, 1]) + + = [1, 0, 1, 0, 1, 0, 1] [List] + + ``` +
+ ### `sum` Sum all elements of a list. @@ -135,6 +425,21 @@ Sum all elements of a list. fn sum(xs: List) -> D ``` +
+Examples + +* Run this example + + ```nbt + >>> sum([3, 2, 1]) + + sum([3, 2, 1]) + + = 6 + + ``` +
+ ### `linspace` Generate a list of `n_steps` evenly spaced numbers from `start` to `end` (inclusive). @@ -142,6 +447,21 @@ Generate a list of `n_steps` evenly spaced numbers from `start` to `end` (inclus fn linspace(start: D, end: D, n_steps: Scalar) -> List ``` +
+Examples + +* Run this example + + ```nbt + >>> linspace(0, 10, 11) + + linspace(0, 10, 11) + + = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10] [List] + + ``` +
+ ### `join` Convert a list of strings into a single string by concatenating them with a separator. @@ -149,6 +469,21 @@ Convert a list of strings into a single string by concatenating them with a sepa fn join(xs: List, sep: String) -> String ``` +
+Examples + +* Run this example + + ```nbt + >>> join(["snake", "case"], "_") + + join(["snake", "case"], "_") + + = "snake_case" [String] + + ``` +
+ ### `split` Split a string into a list of strings using a separator. @@ -156,3 +491,18 @@ Split a string into a list of strings using a separator. fn split(input: String, separator: String) -> List ``` +
+Examples + +* Run this example + + ```nbt + >>> split("Numbat is a statically typed programming language.", " ") + + split("Numbat is a statically typed programming language.", " ") + + = ["Numbat", "is", "a", "statically", "typed", "programming", "language."] [List] + + ``` +
+ diff --git a/book/src/list-functions-math.md b/book/src/list-functions-math.md index 07d7d79f..891d1bfb 100644 --- a/book/src/list-functions-math.md +++ b/book/src/list-functions-math.md @@ -13,6 +13,21 @@ Return the input value. fn id(x: A) -> A ``` +
+Examples + +* Run this example + + ```nbt + >>> id(8kg) + + id(8 kilogram) + + = 8 kg [Mass] + + ``` +
+ ### `abs` (Absolute value) Return the absolute value \\( |x| \\) of the input. This works for quantities, too: `abs(-5 m) = 5 m`. More information [here](https://doc.rust-lang.org/std/primitive.f64.html#method.abs). @@ -21,6 +36,8 @@ More information [here](https://doc.rust-lang.org/std/primitive.f64.html#method. fn abs(x: T) -> T ``` + + ### `sqrt` (Square root) Return the square root \\( \sqrt{x} \\) of the input: `sqrt(121 m^2) = 11 m`. More information [here](https://en.wikipedia.org/wiki/Square_root). @@ -29,6 +46,21 @@ More information [here](https://en.wikipedia.org/wiki/Square_root). fn sqrt(x: D^2) -> D ``` +
+Examples + +* Run this example + + ```nbt + >>> sqrt(4are) -> m + + sqrt(4 are) ➞ metre + + = 20 m [Length] + + ``` +
+ ### `cbrt` (Cube root) Return the cube root \\( \sqrt[3]{x} \\) of the input: `cbrt(8 m^3) = 2 m`. More information [here](https://en.wikipedia.org/wiki/Cube_root). @@ -37,6 +69,21 @@ More information [here](https://en.wikipedia.org/wiki/Cube_root). fn cbrt(x: D^3) -> D ``` +
+Examples + +* Run this example + + ```nbt + >>> cbrt(8l) -> cm + + cbrt(8 litre) ➞ centimetre + + = 20.0 cm [Length] + + ``` +
+ ### `sqr` (Square function) Return the square of the input, \\( x^2 \\): `sqr(5 m) = 25 m^2`. @@ -44,6 +91,21 @@ Return the square of the input, \\( x^2 \\): `sqr(5 m) = 25 m^2`. fn sqr(x: D) -> D^2 ``` +
+Examples + +* Run this example + + ```nbt + >>> sqr(7) + + sqr(7) + + = 49 + + ``` +
+ ### `round` (Rounding) Round to the nearest integer. If the value is half-way between two integers, round away from \\( 0 \\). See also: `round_in`. More information [here](https://doc.rust-lang.org/std/primitive.f64.html#method.round). @@ -52,13 +114,65 @@ More information [here](https://doc.rust-lang.org/std/primitive.f64.html#method. fn round(x: Scalar) -> Scalar ``` +
+Examples + +* Run this example + + ```nbt + >>> round(5.5) + + round(5.5) + + = 6 + + ``` +* Run this example + + ```nbt + >>> round(-5.5) + + round(-5.5) + + = -6 + + ``` +
+ ### `round_in` (Rounding) -Round to the nearest multiple of `base`. For example: `round_in(m, 5.3 m) == 5 m`. +Round to the nearest multiple of `base`. ```nbt fn round_in(base: D, value: D) -> D ``` +
+Examples + +* Round in meters. + + Run this example + ```nbt + >>> round_in(m, 5.3 m) + + round_in(metre, 5.3 metre) + + = 5 m [Length] + + ``` +* Round in centimeters. + + Run this example + ```nbt + >>> round_in(cm, 5.3 m) + + round_in(centimetre, 5.3 metre) + + = 530 cm [Length] + + ``` +
+ ### `floor` (Floor function) Returns the largest integer less than or equal to \\( x \\). See also: `floor_in`. More information [here](https://doc.rust-lang.org/std/primitive.f64.html#method.floor). @@ -67,13 +181,55 @@ More information [here](https://doc.rust-lang.org/std/primitive.f64.html#method. fn floor(x: Scalar) -> Scalar ``` +
+Examples + +* Run this example + + ```nbt + >>> floor(5.5) + + floor(5.5) + + = 5 + + ``` +
+ ### `floor_in` (Floor function) -Returns the largest integer multiple of `base` less than or equal to `value`. For example: `floor_in(m, 5.7 m) == 5 m`. +Returns the largest integer multiple of `base` less than or equal to `value`. ```nbt fn floor_in(base: D, value: D) -> D ``` +
+Examples + +* Floor in meters. + + Run this example + ```nbt + >>> floor_in(m, 5.7 m) + + floor_in(metre, 5.7 metre) + + = 5 m [Length] + + ``` +* Floor in centimeters. + + Run this example + ```nbt + >>> floor_in(cm, 5.7 m) + + floor_in(centimetre, 5.7 metre) + + = 570 cm [Length] + + ``` +
+ ### `ceil` (Ceil function) Returns the smallest integer greater than or equal to \\( x \\). See also: `ceil_in`. More information [here](https://doc.rust-lang.org/std/primitive.f64.html#method.ceil). @@ -82,13 +238,55 @@ More information [here](https://doc.rust-lang.org/std/primitive.f64.html#method. fn ceil(x: Scalar) -> Scalar ``` +
+Examples + +* Run this example + + ```nbt + >>> ceil(5.5) + + ceil(5.5) + + = 6 + + ``` +
+ ### `ceil_in` (Ceil function) -Returns the smallest integer multuple of `base` greater than or equal to `value`. For example: `ceil_in(m, 5.3 m) == 6 m`. +Returns the smallest integer multuple of `base` greater than or equal to `value`. ```nbt fn ceil_in(base: D, value: D) -> D ``` +
+Examples + +* Ceil in meters. + + Run this example + ```nbt + >>> ceil_in(m, 5.3 m) + + ceil_in(metre, 5.3 metre) + + = 6 m [Length] + + ``` +* Ceil in centimeters. + + Run this example + ```nbt + >>> ceil_in(cm, 5.3 m) + + ceil_in(centimetre, 5.3 metre) + + = 530 cm [Length] + + ``` +
+ ### `trunc` (Truncation) Returns the integer part of \\( x \\). Non-integer numbers are always truncated towards zero. See also: `trunc_in`. More information [here](https://doc.rust-lang.org/std/primitive.f64.html#method.trunc). @@ -97,13 +295,65 @@ More information [here](https://doc.rust-lang.org/std/primitive.f64.html#method. fn trunc(x: Scalar) -> Scalar ``` +
+Examples + +* Run this example + + ```nbt + >>> trunc(5.5) + + trunc(5.5) + + = 5 + + ``` +* Run this example + + ```nbt + >>> trunc(-5.5) + + trunc(-5.5) + + = -5 + + ``` +
+ ### `trunc_in` (Truncation) -Truncates to an integer multiple of `base` (towards zero). For example: `trunc_in(m, -5.7 m) == -5 m`. +Truncates to an integer multiple of `base` (towards zero). ```nbt fn trunc_in(base: D, value: D) -> D ``` +
+Examples + +* Truncate in meters. + + Run this example + ```nbt + >>> trunc_in(m, 5.7 m) + + trunc_in(metre, 5.7 metre) + + = 5 m [Length] + + ``` +* Truncate in centimeters. + + Run this example + ```nbt + >>> trunc_in(cm, 5.7 m) + + trunc_in(centimetre, 5.7 metre) + + = 570 cm [Length] + + ``` +
+ ### `mod` (Modulo) Calculates the least nonnegative remainder of \\( a (\mod b) \\). More information [here](https://doc.rust-lang.org/std/primitive.f64.html#method.rem_euclid). @@ -112,6 +362,21 @@ More information [here](https://doc.rust-lang.org/std/primitive.f64.html#method. fn mod(a: T, b: T) -> T ``` +
+Examples + +* Run this example + + ```nbt + >>> mod(27, 5) + + mod(27, 5) + + = 2 + + ``` +
+ ## Transcendental functions Defined in: `math::transcendental` @@ -124,6 +389,21 @@ More information [here](https://en.wikipedia.org/wiki/Exponential_function). fn exp(x: Scalar) -> Scalar ``` +
+Examples + +* Run this example + + ```nbt + >>> exp(4) + + exp(4) + + = 54.5982 + + ``` +
+ ### `ln` (Natural logarithm) The natural logarithm with base \\( e \\). More information [here](https://en.wikipedia.org/wiki/Natural_logarithm). @@ -132,6 +412,21 @@ More information [here](https://en.wikipedia.org/wiki/Natural_logarithm). fn ln(x: Scalar) -> Scalar ``` +
+Examples + +* Run this example + + ```nbt + >>> ln(20) + + ln(20) + + = 2.99573 + + ``` +
+ ### `log` (Natural logarithm) The natural logarithm with base \\( e \\). More information [here](https://en.wikipedia.org/wiki/Natural_logarithm). @@ -140,6 +435,21 @@ More information [here](https://en.wikipedia.org/wiki/Natural_logarithm). fn log(x: Scalar) -> Scalar ``` +
+Examples + +* Run this example + + ```nbt + >>> log(20) + + log(20) + + = 2.99573 + + ``` +
+ ### `log10` (Common logarithm) The common logarithm with base \\( 10 \\). More information [here](https://en.wikipedia.org/wiki/Common_logarithm). @@ -148,6 +458,21 @@ More information [here](https://en.wikipedia.org/wiki/Common_logarithm). fn log10(x: Scalar) -> Scalar ``` +
+Examples + +* Run this example + + ```nbt + >>> log10(100) + + log10(100) + + = 2 + + ``` +
+ ### `log2` (Binary logarithm) The binary logarithm with base \\( 2 \\). More information [here](https://en.wikipedia.org/wiki/Binary_logarithm). @@ -156,6 +481,21 @@ More information [here](https://en.wikipedia.org/wiki/Binary_logarithm). fn log2(x: Scalar) -> Scalar ``` +
+Examples + +* Run this example + + ```nbt + >>> log2(256) + + log2(256) + + = 8 + + ``` +
+ ### `gamma` (Gamma function) The gamma function, \\( \Gamma(x) \\). More information [here](https://en.wikipedia.org/wiki/Gamma_function). @@ -164,6 +504,8 @@ More information [here](https://en.wikipedia.org/wiki/Gamma_function). fn gamma(x: Scalar) -> Scalar ``` + + ## Trigonometry Defined in: `math::trigonometry` @@ -175,6 +517,8 @@ More information [here](https://en.wikipedia.org/wiki/Trigonometric_functions). fn sin(x: Scalar) -> Scalar ``` + + ### `cos` (Cosine) More information [here](https://en.wikipedia.org/wiki/Trigonometric_functions). @@ -182,6 +526,8 @@ More information [here](https://en.wikipedia.org/wiki/Trigonometric_functions). fn cos(x: Scalar) -> Scalar ``` + + ### `tan` (Tangent) More information [here](https://en.wikipedia.org/wiki/Trigonometric_functions). @@ -189,6 +535,8 @@ More information [here](https://en.wikipedia.org/wiki/Trigonometric_functions). fn tan(x: Scalar) -> Scalar ``` + + ### `asin` (Arc sine) More information [here](https://en.wikipedia.org/wiki/Inverse_trigonometric_functions). @@ -196,6 +544,8 @@ More information [here](https://en.wikipedia.org/wiki/Inverse_trigonometric_func fn asin(x: Scalar) -> Scalar ``` + + ### `acos` (Arc cosine) More information [here](https://en.wikipedia.org/wiki/Inverse_trigonometric_functions). @@ -203,6 +553,8 @@ More information [here](https://en.wikipedia.org/wiki/Inverse_trigonometric_func fn acos(x: Scalar) -> Scalar ``` + + ### `atan` (Arc tangent) More information [here](https://en.wikipedia.org/wiki/Inverse_trigonometric_functions). @@ -210,6 +562,8 @@ More information [here](https://en.wikipedia.org/wiki/Inverse_trigonometric_func fn atan(x: Scalar) -> Scalar ``` + + ### `atan2` More information [here](https://en.wikipedia.org/wiki/Atan2). @@ -217,6 +571,8 @@ More information [here](https://en.wikipedia.org/wiki/Atan2). fn atan2(y: T, x: T) -> Scalar ``` + + ### `sinh` (Hyperbolic sine) More information [here](https://en.wikipedia.org/wiki/Hyperbolic_functions). @@ -224,6 +580,8 @@ More information [here](https://en.wikipedia.org/wiki/Hyperbolic_functions). fn sinh(x: Scalar) -> Scalar ``` + + ### `cosh` (Hyperbolic cosine) More information [here](https://en.wikipedia.org/wiki/Hyperbolic_functions). @@ -231,6 +589,8 @@ More information [here](https://en.wikipedia.org/wiki/Hyperbolic_functions). fn cosh(x: Scalar) -> Scalar ``` + + ### `tanh` (Hyperbolic tangent) More information [here](https://en.wikipedia.org/wiki/Hyperbolic_functions). @@ -238,6 +598,8 @@ More information [here](https://en.wikipedia.org/wiki/Hyperbolic_functions). fn tanh(x: Scalar) -> Scalar ``` + + ### `asinh` (Area hyperbolic sine) More information [here](https://en.wikipedia.org/wiki/Hyperbolic_functions). @@ -245,6 +607,8 @@ More information [here](https://en.wikipedia.org/wiki/Hyperbolic_functions). fn asinh(x: Scalar) -> Scalar ``` + + ### `acosh` (Area hyperbolic cosine) More information [here](https://en.wikipedia.org/wiki/Hyperbolic_functions). @@ -252,6 +616,8 @@ More information [here](https://en.wikipedia.org/wiki/Hyperbolic_functions). fn acosh(x: Scalar) -> Scalar ``` + + ### `atanh` (Area hyperbolic tangent ) More information [here](https://en.wikipedia.org/wiki/Hyperbolic_functions). @@ -259,32 +625,79 @@ More information [here](https://en.wikipedia.org/wiki/Hyperbolic_functions). fn atanh(x: Scalar) -> Scalar ``` + + ## Statistics Defined in: `math::statistics` ### `maximum` (Maxmimum) -Get the largest element of a list: `maximum([30 cm, 2 m]) = 2 m`. +Get the largest element of a list. ```nbt fn maximum(xs: List) -> D ``` +
+Examples + +* Run this example + + ```nbt + >>> maximum([30 cm, 2 m]) + + maximum([30 centimetre, 2 metre]) + + = 2 m [Length] + + ``` +
+ ### `minimum` (Minimum) -Get the smallest element of a list: `minimum([30 cm, 2 m]) = 30 cm`. +Get the smallest element of a list. ```nbt fn minimum(xs: List) -> D ``` +
+Examples + +* Run this example + + ```nbt + >>> minimum([30 cm, 2 m]) + + minimum([30 centimetre, 2 metre]) + + = 30 cm [Length] + + ``` +
+ ### `mean` (Arithmetic mean) -Calculate the arithmetic mean of a list of quantities: `mean([1 m, 2 m, 300 cm]) = 2 m`. +Calculate the arithmetic mean of a list of quantities. More information [here](https://en.wikipedia.org/wiki/Arithmetic_mean). ```nbt fn mean(xs: List) -> D ``` +
+Examples + +* Run this example + + ```nbt + >>> mean([1 m, 2 m, 300 cm]) + + mean([1 metre, 2 metre, 300 centimetre]) + + = 2 m [Length] + + ``` +
+ ### `variance` (Variance) Calculate the population variance of a list of quantities. More information [here](https://en.wikipedia.org/wiki/Variance). @@ -293,6 +706,21 @@ More information [here](https://en.wikipedia.org/wiki/Variance). fn variance(xs: List) -> D^2 ``` +
+Examples + +* Run this example + + ```nbt + >>> variance([1 m, 2 m, 300 cm]) + + variance([1 metre, 2 metre, 300 centimetre]) + + = 0.666667 m² [Area] + + ``` +
+ ### `stdev` (Standard deviation) Calculate the population standard deviation of a list of quantities. More information [here](https://en.wikipedia.org/wiki/Standard_deviation). @@ -301,6 +729,21 @@ More information [here](https://en.wikipedia.org/wiki/Standard_deviation). fn stdev(xs: List) -> D ``` +
+Examples + +* Run this example + + ```nbt + >>> stdev([1 m, 2 m, 300 cm]) + + stdev([1 metre, 2 metre, 300 centimetre]) + + = 0.816497 m [Length] + + ``` +
+ ### `median` (Median) Calculate the median of a list of quantities. More information [here](https://en.wikipedia.org/wiki/Median). @@ -309,6 +752,21 @@ More information [here](https://en.wikipedia.org/wiki/Median). fn median(xs: List) -> D ``` +
+Examples + +* Run this example + + ```nbt + >>> median([1 m, 2 m, 400 cm]) + + median([1 metre, 2 metre, 400 centimetre]) + + = 2 m [Length] + + ``` +
+ ## Random sampling, distributions Defined in: `core::random`, `math::distributions` @@ -320,6 +778,8 @@ Uniformly samples the interval \\( [0,1) \\). fn random() -> Scalar ``` + + ### `rand_uniform` (Continuous uniform distribution sampling) Uniformly samples the interval \\( [a,b) \\) if \\( a \le b \\) or \\( [b,a) \\) if \\( b(a: T, b: T) -> T ``` + + ### `rand_int` (Discrete uniform distribution sampling) Uniformly samples integers from the interval \\( [a, b] \\). More information [here](https://en.wikipedia.org/wiki/Discrete_uniform_distribution). @@ -336,6 +798,8 @@ More information [here](https://en.wikipedia.org/wiki/Discrete_uniform_distribut fn rand_int(a: Scalar, b: Scalar) -> Scalar ``` + + ### `rand_bernoulli` (Bernoulli distribution sampling) Samples a Bernoulli random variable. That is, \\( 1 \\) with probability \\( p \\) and \\( 0 \\) with probability \\( 1-p \\). The parameter \\( p \\) must be a probability (\\( 0 \le p \le 1 \\)). More information [here](https://en.wikipedia.org/wiki/Bernoulli_distribution). @@ -344,6 +808,8 @@ More information [here](https://en.wikipedia.org/wiki/Bernoulli_distribution). fn rand_bernoulli(p: Scalar) -> Scalar ``` + + ### `rand_binom` (Binomial distribution sampling) Samples a binomial distribution by doing \\( n \\) Bernoulli trials with probability \\( p \\). The parameter \\( n \\) must be a positive integer, the parameter \\( p \\) must be a probability (\\( 0 \le p \le 1 \\)). @@ -353,6 +819,8 @@ More information [here](https://en.wikipedia.org/wiki/Binomial_distribution). fn rand_binom(n: Scalar, p: Scalar) -> Scalar ``` + + ### `rand_norm` (Normal distribution sampling) Samples a normal distribution with mean \\( \mu \\) and standard deviation \\( \sigma \\) using the Box-Muller transform. More information [here](https://en.wikipedia.org/wiki/Normal_distribution). @@ -361,6 +829,8 @@ More information [here](https://en.wikipedia.org/wiki/Normal_distribution). fn rand_norm(μ: T, σ: T) -> T ``` + + ### `rand_geom` (Geometric distribution sampling) Samples a geometric distribution (the distribution of the number of Bernoulli trials with probability \\( p \\) needed to get one success) by inversion sampling. The parameter \\( p \\) must be a probability (\\( 0 \le p \le 1 \\)). More information [here](https://en.wikipedia.org/wiki/Geometric_distribution). @@ -369,6 +839,8 @@ More information [here](https://en.wikipedia.org/wiki/Geometric_distribution). fn rand_geom(p: Scalar) -> Scalar ``` + + ### `rand_poisson` (Poisson distribution sampling) Sampling a poisson distribution with rate \\( \lambda \\), that is, the distribution of the number of events occurring in a fixed interval if these events occur with mean rate \\( \lambda \\). The rate parameter \\( \lambda \\) must be non-negative. More information [here](https://en.wikipedia.org/wiki/Poisson_distribution). @@ -377,6 +849,8 @@ More information [here](https://en.wikipedia.org/wiki/Poisson_distribution). fn rand_poisson(λ: Scalar) -> Scalar ``` + + ### `rand_expon` (Exponential distribution sampling) Sampling an exponential distribution (the distribution of the distance between events in a Poisson process with rate \\( \lambda \\)) using inversion sampling. The rate parameter \\( \lambda \\) must be positive. More information [here](https://en.wikipedia.org/wiki/Exponential_distribution). @@ -385,6 +859,8 @@ More information [here](https://en.wikipedia.org/wiki/Exponential_distribution). fn rand_expon(λ: T) -> 1 / T ``` + + ### `rand_lognorm` (Log-normal distribution sampling) Sampling a log-normal distribution, that is, a distribution whose logarithm is a normal distribution with mean \\( \mu \\) and standard deviation \\( \sigma \\). More information [here](https://en.wikipedia.org/wiki/Log-normal_distribution). @@ -393,6 +869,8 @@ More information [here](https://en.wikipedia.org/wiki/Log-normal_distribution). fn rand_lognorm(μ: Scalar, σ: Scalar) -> Scalar ``` + + ### `rand_pareto` (Pareto distribution sampling) Sampling a Pareto distribution with minimum value `min` and shape parameter \\( \alpha \\) using inversion sampling. Both parameters must be positive. More information [here](https://en.wikipedia.org/wiki/Pareto_distribution). @@ -401,6 +879,8 @@ More information [here](https://en.wikipedia.org/wiki/Pareto_distribution). fn rand_pareto(α: Scalar, min: T) -> T ``` + + ## Number theory Defined in: `math::number_theory` @@ -413,6 +893,21 @@ More information [here](https://en.wikipedia.org/wiki/Greatest_common_divisor). fn gcd(a: Scalar, b: Scalar) -> Scalar ``` +
+Examples + +* Run this example + + ```nbt + >>> gcd(60,42) + + gcd(60, 42) + + = 6 + + ``` +
+ ### `lcm` (Least common multiple) The smallest positive integer that is divisible by both \\( a \\) and \\( b \\). More information [here](https://en.wikipedia.org/wiki/Least_common_multiple). @@ -421,6 +916,21 @@ More information [here](https://en.wikipedia.org/wiki/Least_common_multiple). fn lcm(a: Scalar, b: Scalar) -> Scalar ``` +
+Examples + +* Run this example + + ```nbt + >>> lcm(14, 4) + + lcm(14, 4) + + = 28 + + ``` +
+ ## Numerical methods Defined in: `numerics::diff`, `numerics::solve`, `numerics::fixed_point` @@ -433,6 +943,25 @@ More information [here](https://en.wikipedia.org/wiki/Numerical_differentiation) fn diff(f: Fn[(X) -> Y], x: X) -> Y / X ``` +
+Examples + +* Compute the drivative of \\( f(x) = x² -x -1 \\) at \\( x=1 \\). + + Run this example + ```nbt + >>> fn polynomial(x) = x² -x -1 + diff(polynomial, 1) + + fn polynomial(x: Scalar) -> Scalar = (x² - x) - 1 + + diff(polynomial, 1) + + = 1.0 + + ``` +
+ ### `root_bisect` (Bisection method) Find the root of the function \\( f \\) in the interval \\( [x_1, x_2] \\) using the bisection method. The function \\( f \\) must be continuous and \\( f(x_1) \cdot f(x_2) < 0 \\). More information [here](https://en.wikipedia.org/wiki/Bisection_method). @@ -441,6 +970,25 @@ More information [here](https://en.wikipedia.org/wiki/Bisection_method). fn root_bisect(f: Fn[(X) -> Y], x1: X, x2: X, x_tol: X, y_tol: Y) -> X ``` +
+Examples + +* Find the root of \\( f(x) = x² +x -2 \\) in the interval \\( [0, 100] \\). + + Run this example + ```nbt + >>> fn f(x) = x² +x -2 + root_bisect(f, 0, 100, 0.01, 0.01) + + fn f(x: Scalar) -> Scalar = (x² + x) - 2 + + root_bisect(f, 0, 100, 0.01, 0.01) + + = 1.00098 + + ``` +
+ ### `root_newton` (Newton's method) Find the root of the function \\( f(x) \\) and its derivative \\( f'(x) \\) using Newton's method. More information [here](https://en.wikipedia.org/wiki/Newton%27s_method). @@ -449,6 +997,28 @@ More information [here](https://en.wikipedia.org/wiki/Newton%27s_method). fn root_newton(f: Fn[(X) -> Y], f_prime: Fn[(X) -> Y / X], x0: X, y_tol: Y) -> X ``` +
+Examples + +* Find a root of \\( f(x) = x² -3x +2 \\) using Newton's method. + + Run this example + ```nbt + >>> fn f(x) = x² -3x +2 + fn f_prime(x) = 2x -3 + root_newton(f, f_prime, 0 , 0.01) + + fn f(x: Scalar) -> Scalar = (x² - 3 x) + 2 + + fn f_prime(x: Scalar) -> Scalar = 2 x - 3 + + root_newton(f, f_prime, 0, 0.01) + + = 0.996078 + + ``` +
+ ### `fixed_point` (Fixed-point iteration) Compute the approximate fixed point of a function \\( f: X \rightarrow X \\) starting from \\( x_0 \\), until \\( |f(x) - x| < ε \\). More information [here](https://en.wikipedia.org/wiki/Fixed-point_iteration). @@ -457,6 +1027,25 @@ More information [here](https://en.wikipedia.org/wiki/Fixed-point_iteration). fn fixed_point(f: Fn[(X) -> X], x0: X, ε: X) -> X ``` +
+Examples + +* Compute the fixed poin of \\( f(x) = x/2 -1 \\). + + Run this example + ```nbt + >>> fn function(x) = x/2 - 1 + fixed_point(function, 0, 0.01) + + fn function(x: Scalar) -> Scalar = (x / 2) - 1 + + fixed_point(function, 0, 0.01) + + = -1.99219 + + ``` +
+ ## Geometry Defined in: `math::geometry` @@ -468,6 +1057,21 @@ The length of the hypotenuse of a right-angled triangle \\( \sqrt{x^2+y^2} \\). fn hypot2(x: T, y: T) -> T ``` +
+Examples + +* Run this example + + ```nbt + >>> hypot2(3, 4) + + hypot2(3, 4) + + = 5 + + ``` +
+ ### `hypot3` The Euclidean norm of a 3D vector \\( \sqrt{x^2+y^2+z^2} \\). @@ -475,6 +1079,21 @@ The Euclidean norm of a 3D vector \\( \sqrt{x^2+y^2+z^2} \\). fn hypot3(x: T, y: T, z: T) -> T ``` +
+Examples + +* Run this example + + ```nbt + >>> hypot3(4, 1, 4) + + hypot3(4, 1, 4) + + = 5.74456 + + ``` +
+ ### `circle_area` The area of a circle, \\( \pi r^2 \\). @@ -482,6 +1101,8 @@ The area of a circle, \\( \pi r^2 \\). fn circle_area(radius: L) -> L^2 ``` + + ### `circle_circumference` The circumference of a circle, \\( 2\pi r \\). @@ -489,6 +1110,8 @@ The circumference of a circle, \\( 2\pi r \\). fn circle_circumference(radius: L) -> L ``` + + ### `sphere_area` The surface area of a sphere, \\( 4\pi r^2 \\). @@ -496,6 +1119,8 @@ The surface area of a sphere, \\( 4\pi r^2 \\). fn sphere_area(radius: L) -> L^2 ``` + + ### `sphere_volume` The volume of a sphere, \\( \frac{4}{3}\pi r^3 \\). @@ -503,6 +1128,8 @@ The volume of a sphere, \\( \frac{4}{3}\pi r^3 \\). fn sphere_volume(radius: L) -> L^3 ``` + + ## Algebra Defined in: `extra::algebra` @@ -515,6 +1142,22 @@ More information [here](https://en.wikipedia.org/wiki/Quadratic_equation). fn quadratic_equation(a: A, b: B, c: B^2 / A) -> List ``` +
+Examples + +* Solve the equation \\( 2x² -x -1 = 0 \\) + + Run this example + ```nbt + >>> quadratic_equation(2, -1, -1) + + quadratic_equation(2, -1, -1) + + = [1, -0.5] [List] + + ``` +
+ ## Trigonometry (extra) Defined in: `math::trigonometry_extra` @@ -525,75 +1168,101 @@ Defined in: `math::trigonometry_extra` fn cot(x: Scalar) -> Scalar ``` + + ### `acot` ```nbt fn acot(x: Scalar) -> Scalar ``` + + ### `coth` ```nbt fn coth(x: Scalar) -> Scalar ``` + + ### `acoth` ```nbt fn acoth(x: Scalar) -> Scalar ``` + + ### `secant` ```nbt fn secant(x: Scalar) -> Scalar ``` + + ### `arcsecant` ```nbt fn arcsecant(x: Scalar) -> Scalar ``` + + ### `cosecant` ```nbt fn cosecant(x: Scalar) -> Scalar ``` + + ### `csc` ```nbt fn csc(x: Scalar) -> Scalar ``` + + ### `acsc` ```nbt fn acsc(x: Scalar) -> Scalar ``` + + ### `sech` ```nbt fn sech(x: Scalar) -> Scalar ``` + + ### `asech` ```nbt fn asech(x: Scalar) -> Scalar ``` + + ### `csch` ```nbt fn csch(x: Scalar) -> Scalar ``` + + ### `acsch` ```nbt fn acsch(x: Scalar) -> Scalar ``` + + diff --git a/book/src/list-functions-other.md b/book/src/list-functions-other.md index a8a97830..90363f6f 100644 --- a/book/src/list-functions-other.md +++ b/book/src/list-functions-other.md @@ -13,6 +13,8 @@ Throw an error with the specified message. Stops the execution of the program. fn error(message: String) -> T ``` + + ## Floating point Defined in: `core::numbers` @@ -25,6 +27,31 @@ More information [here](https://doc.rust-lang.org/std/primitive.f64.html#method. fn is_nan(n: T) -> Bool ``` +
+Examples + +* Run this example + + ```nbt + >>> is_nan(37) + + is_nan(37) + + = false [Bool] + + ``` +* Run this example + + ```nbt + >>> is_nan(NaN) + + is_nan(NaN) + + = true [Bool] + + ``` +
+ ### `is_infinite` Returns true if the input is positive infinity or negative infinity. More information [here](https://doc.rust-lang.org/std/primitive.f64.html#method.is_infinite). @@ -33,6 +60,31 @@ More information [here](https://doc.rust-lang.org/std/primitive.f64.html#method. fn is_infinite(n: T) -> Bool ``` +
+Examples + +* Run this example + + ```nbt + >>> is_infinite(37) + + is_infinite(37) + + = false [Bool] + + ``` +* Run this example + + ```nbt + >>> is_infinite(-inf) + + is_infinite(-inf) + + = true [Bool] + + ``` +
+ ### `is_finite` Returns true if the input is neither infinite nor `NaN`. @@ -40,6 +92,31 @@ Returns true if the input is neither infinite nor `NaN`. fn is_finite(n: T) -> Bool ``` +
+Examples + +* Run this example + + ```nbt + >>> is_finite(37) + + is_finite(37) + + = true [Bool] + + ``` +* Run this example + + ```nbt + >>> is_finite(-inf) + + is_finite(-inf) + + = false [Bool] + + ``` +
+ ## Quantities Defined in: `core::quantities` @@ -51,6 +128,21 @@ Extract the unit of a quantity (the `km/h` in `20 km/h`). This can be useful in fn unit_of(x: T) -> T ``` +
+Examples + +* Run this example + + ```nbt + >>> unit_of(20 km/h) + + unit_of(20 kilometre / hour) + + = 1 km/h [Velocity] + + ``` +
+ ### `value_of` Extract the plain value of a quantity (the `20` in `20 km/h`). This can be useful in generic code, but should generally be avoided otherwise. @@ -58,17 +150,59 @@ Extract the plain value of a quantity (the `20` in `20 km/h`). This can be usefu fn value_of(x: T) -> Scalar ``` +
+Examples + +* Run this example + + ```nbt + >>> value_of(20 km/h) + + value_of(20 kilometre / hour) + + = 20 + + ``` +
+ ## Chemical elements Defined in: `chemistry::elements` ### `element` (Chemical element) -Get properties of a chemical element by its symbol or name (case-insensitive). For example: `element("H")` or `element("hydrogen")`. +Get properties of a chemical element by its symbol or name (case-insensitive). ```nbt fn element(pattern: String) -> ChemicalElement ``` +
+Examples + +* Get the entire element struct for hydrogen. + + Run this example + ```nbt + >>> element("H") + + element("H") + + = ChemicalElement { symbol: "H", name: "Hydrogen", atomic_number: 1, group: 1, group_name: "Alkali metals", period: 1, melting_point: 13.99 K, boiling_point: 20.271 K, density: 0.00008988 g/cm³, electron_affinity: 0.754 eV, ionization_energy: 13.598 eV, vaporization_heat: 0.904 kJ/mol } [ChemicalElement] + + ``` +* Get the ionization energy of hydrogen. + + Run this example + ```nbt + >>> element("hydrogen").ionization_energy + + element("hydrogen").ionization_energy + + = 13.598 eV [Energy or Torque] + + ``` +
+ ## Mixed unit conversion Defined in: `units::mixed` @@ -81,6 +215,21 @@ More information [here](https://en.wikipedia.org/wiki/Sexagesimal_degree). fn DMS(alpha: Angle) -> String ``` +
+Examples + +* Run this example + + ```nbt + >>> DMS(46.5858°) + + DMS(46.5858 degree) + + = "46° 35′ 9″" [String] + + ``` +
+ ### `DM` (Degrees, decimal minutes) Convert an angle to a mixed degrees and decimal minutes representation. More information [here](https://en.wikipedia.org/wiki/Decimal_degrees). @@ -89,6 +238,21 @@ More information [here](https://en.wikipedia.org/wiki/Decimal_degrees). fn DM(alpha: Angle) -> String ``` +
+Examples + +* Run this example + + ```nbt + >>> DM(46.5858°) + + DM(46.5858 degree) + + = "46° 35.148′" [String] + + ``` +
+ ### `feet_and_inches` (Feet and inches) Convert a length to a mixed feet and inches representation. More information [here](https://en.wikipedia.org/wiki/Foot_(unit)). @@ -97,6 +261,21 @@ More information [here](https://en.wikipedia.org/wiki/Foot_(unit)). fn feet_and_inches(length: Length) -> String ``` +
+Examples + +* Run this example + + ```nbt + >>> feet_and_inches(180cm) + + feet_and_inches(180 centimetre) + + = "5 ft 10.8661 in" [String] + + ``` +
+ ### `pounds_and_ounces` (Pounds and ounces) Convert a mass to a mixed pounds and ounces representation. More information [here](https://en.wikipedia.org/wiki/Pound_(mass)). @@ -105,6 +284,21 @@ More information [here](https://en.wikipedia.org/wiki/Pound_(mass)). fn pounds_and_ounces(mass: Mass) -> String ``` +
+Examples + +* Run this example + + ```nbt + >>> pounds_and_ounces(1kg) + + pounds_and_ounces(1 kilogram) + + = "2 lb 3.27396 oz" [String] + + ``` +
+ ## Temperature conversion Defined in: `physics::temperature_conversion` @@ -117,6 +311,22 @@ More information [here](https://en.wikipedia.org/wiki/Conversion_of_scales_of_te fn from_celsius(t_celsius: Scalar) -> Temperature ``` +
+Examples + +* \\( 300 °C \\) in Kelvin. + + Run this example + ```nbt + >>> from_celsius(300) + + from_celsius(300) + + = 573.15 K [Temperature] + + ``` +
+ ### `celsius` Converts from Kelvin to degree Celcius (°C). This can be used on the right hand side of a conversion operator: `200 K -> celsius`. More information [here](https://en.wikipedia.org/wiki/Conversion_of_scales_of_temperature). @@ -125,6 +335,22 @@ More information [here](https://en.wikipedia.org/wiki/Conversion_of_scales_of_te fn celsius(t_kelvin: Temperature) -> Scalar ``` +
+Examples + +* \\( 300K \\) in degree Celsius. + + Run this example + ```nbt + >>> 300K -> celsius + + celsius(300 kelvin) + + = 26.85 + + ``` +
+ ### `from_fahrenheit` Converts from degree Fahrenheit (°F) to Kelvin. More information [here](https://en.wikipedia.org/wiki/Conversion_of_scales_of_temperature). @@ -133,6 +359,22 @@ More information [here](https://en.wikipedia.org/wiki/Conversion_of_scales_of_te fn from_fahrenheit(t_fahrenheit: Scalar) -> Temperature ``` +
+Examples + +* \\( 300 °F \\) in Kelvin. + + Run this example + ```nbt + >>> from_fahrenheit(300) + + from_fahrenheit(300) + + = 422.039 K [Temperature] + + ``` +
+ ### `fahrenheit` Converts from Kelvin to degree Fahrenheit (°F). This can be used on the right hand side of a conversion operator: `200 K -> fahrenheit`. More information [here](https://en.wikipedia.org/wiki/Conversion_of_scales_of_temperature). @@ -141,6 +383,22 @@ More information [here](https://en.wikipedia.org/wiki/Conversion_of_scales_of_te fn fahrenheit(t_kelvin: Temperature) -> Scalar ``` +
+Examples + +* \\( 300K \\) in degree Fahrenheit. + + Run this example + ```nbt + >>> 300K -> fahrenheit + + fahrenheit(300 kelvin) + + = 80.33 + + ``` +
+ ## Color format conversion Defined in: `extra::color` @@ -152,31 +410,106 @@ Create a `Color` from RGB (red, green, blue) values in the range \\( [0, 256) \\ fn rgb(red: Scalar, green: Scalar, blue: Scalar) -> Color ``` +
+Examples + +* Run this example + + ```nbt + >>> rgb(125, 128, 218) + + rgb(125, 128, 218) + + = Color { red: 125, green: 128, blue: 218 } [Color] + + ``` +
+ ### `color` -Create a `Color` from a (hexadecimal) value, e.g. `color(0xff7700)`. +Create a `Color` from a (hexadecimal) value. ```nbt fn color(rgb_hex: Scalar) -> Color ``` +
+Examples + +* Run this example + + ```nbt + >>> color(0xff7700) + + color(16_742_144) + + = Color { red: 255, green: 119, blue: 0 } [Color] + + ``` +
+ ### `color_rgb` -Convert a color to its RGB representation, e.g. `cyan -> color_rgb`. +Convert a color to its RGB representation. ```nbt fn color_rgb(color: Color) -> String ``` +
+Examples + +* Run this example + + ```nbt + >>> cyan -> color_rgb + + color_rgb(cyan) + + = "rgb(0, 255, 255)" [String] + + ``` +
+ ### `color_rgb_float` -Convert a color to its RGB floating point representation, e.g. `cyan -> color_rgb_float`. +Convert a color to its RGB floating point representation. ```nbt fn color_rgb_float(color: Color) -> String ``` +
+Examples + +* Run this example + + ```nbt + >>> cyan -> color_rgb_float + + color_rgb_float(cyan) + + = "rgb(0.000, 1.000, 1.000)" [String] + + ``` +
+ ### `color_hex` -Convert a color to its hexadecimal representation, e.g. `rgb(225, 36, 143) -> color_hex`. +Convert a color to its hexadecimal representation. ```nbt fn color_hex(color: Color) -> String ``` +
+Examples + +* Run this example + + ```nbt + >>> rgb(225, 36, 143) -> color_hex + + color_hex(rgb(225, 36, 143)) + + = "#e1248f" [String] + + ``` +
+ diff --git a/book/src/list-functions-strings.md b/book/src/list-functions-strings.md index e955338c..b8ca8b78 100644 --- a/book/src/list-functions-strings.md +++ b/book/src/list-functions-strings.md @@ -9,6 +9,21 @@ The length of a string. fn str_length(s: String) -> Scalar ``` +
+Examples + +* Run this example + + ```nbt + >>> str_length("Numbat") + + str_length("Numbat") + + = 6 + + ``` +
+ ### `str_slice` Subslice of a string. @@ -16,20 +31,65 @@ Subslice of a string. fn str_slice(s: String, start: Scalar, end: Scalar) -> String ``` +
+Examples + +* Run this example + + ```nbt + >>> str_slice("Numbat", 0, 2) + + str_slice("Numbat", 0, 2) + + = "Nu" [String] + + ``` +
+ ### `chr` -Get a single-character string from a Unicode code point. Example: `0x2764 -> chr`. +Get a single-character string from a Unicode code point. ```nbt fn chr(n: Scalar) -> String ``` +
+Examples + +* Run this example + + ```nbt + >>> 0x2764 -> chr + + chr(10084) + + = "❤" [String] + + ``` +
+ ### `ord` -Get the Unicode code point of the first character in a string. Example: `"❤" -> ord`. +Get the Unicode code point of the first character in a string. ```nbt fn ord(s: String) -> Scalar ``` +
+Examples + +* Run this example + + ```nbt + >>> "❤" -> ord + + ord("❤") + + = 10084 + + ``` +
+ ### `lowercase` Convert a string to lowercase. @@ -37,6 +97,21 @@ Convert a string to lowercase. fn lowercase(s: String) -> String ``` +
+Examples + +* Run this example + + ```nbt + >>> lowercase("Numbat") + + lowercase("Numbat") + + = "numbat" [String] + + ``` +
+ ### `uppercase` Convert a string to uppercase. @@ -44,6 +119,21 @@ Convert a string to uppercase. fn uppercase(s: String) -> String ``` +
+Examples + +* Run this example + + ```nbt + >>> uppercase("Numbat") + + uppercase("Numbat") + + = "NUMBAT" [String] + + ``` +
+ ### `str_append` Concatenate two strings. @@ -51,6 +141,21 @@ Concatenate two strings. fn str_append(a: String, b: String) -> String ``` +
+Examples + +* Run this example + + ```nbt + >>> str_append("Numbat","!") + + str_append("Numbat", "!") + + = "Numbat!" [String] + + ``` +
+ ### `str_find` Find the first occurrence of a substring in a string. @@ -58,6 +163,21 @@ Find the first occurrence of a substring in a string. fn str_find(haystack: String, needle: String) -> Scalar ``` +
+Examples + +* Run this example + + ```nbt + >>> str_find("Numbat is a statically typed programming language.", "typed") + + str_find("Numbat is a statically typed programming language.", "typed") + + = 23 + + ``` +
+ ### `str_contains` Check if a string contains a substring. @@ -65,6 +185,21 @@ Check if a string contains a substring. fn str_contains(haystack: String, needle: String) -> Bool ``` +
+Examples + +* Run this example + + ```nbt + >>> str_contains("Numbat is a statically typed programming language.", "typed") + + str_contains("Numbat is a statically typed programming language.", "typed") + + = true [Bool] + + ``` +
+ ### `str_replace` Replace all occurrences of a substring in a string. @@ -72,6 +207,21 @@ Replace all occurrences of a substring in a string. fn str_replace(s: String, pattern: String, replacement: String) -> String ``` +
+Examples + +* Run this example + + ```nbt + >>> str_replace("Numbat is a statically typed programming language.", "statically typed programming language", "scientific calculator") + + str_replace("Numbat is a statically typed programming language.", "statically typed programming language", "scientific calculator") + + = "Numbat is a scientific calculator." [String] + + ``` +
+ ### `str_repeat` Repeat the input string `n` times. @@ -79,27 +229,87 @@ Repeat the input string `n` times. fn str_repeat(a: String, n: Scalar) -> String ``` +
+Examples + +* Run this example + + ```nbt + >>> str_repeat("abc", 4) + + str_repeat("abc", 4) + + = "abcabcabcabc" [String] + + ``` +
+ ### `base` -Convert a number to the given base. Example: `42 |> base(16)`. +Convert a number to the given base. ```nbt fn base(b: Scalar, x: Scalar) -> String ``` +
+Examples + +* Run this example + + ```nbt + >>> 42 |> base(16) + + base(16, 42) + + = "2a" [String] + + ``` +
+ ### `bin` -Get a binary representation of a number. Example: `42 -> bin`. +Get a binary representation of a number. ```nbt fn bin(x: Scalar) -> String ``` +
+Examples + +* Run this example + + ```nbt + >>> 42 -> bin + + bin(42) + + = "0b101010" [String] + + ``` +
+ ### `oct` -Get an octal representation of a number. Example: `42 -> oct`. +Get an octal representation of a number. ```nbt fn oct(x: Scalar) -> String ``` +
+Examples + +* Run this example + + ```nbt + >>> 42 -> oct + + oct(42) + + = "0o52" [String] + + ``` +
+ ### `dec` Get a decimal representation of a number. @@ -107,10 +317,40 @@ Get a decimal representation of a number. fn dec(x: Scalar) -> String ``` +
+Examples + +* Run this example + + ```nbt + >>> 0b111 -> dec + + dec(7) + + = "7" [String] + + ``` +
+ ### `hex` -Get a hexadecimal representation of a number. Example: `2^31-1 -> hex`. +Get a hexadecimal representation of a number. ```nbt fn hex(x: Scalar) -> String ``` +
+Examples + +* Run this example + + ```nbt + >>> 2^31-1 -> hex + + hex(2^31 - 1) + + = "0x7fffffff" [String] + + ``` +
+ diff --git a/numbat/modules/chemistry/elements.nbt b/numbat/modules/chemistry/elements.nbt index 17d74bb3..e77fed50 100644 --- a/numbat/modules/chemistry/elements.nbt +++ b/numbat/modules/chemistry/elements.nbt @@ -49,6 +49,8 @@ fn _convert_from_raw(raw: _ChemicalElementRaw) -> ChemicalElement = } @name("Chemical element") -@description("Get properties of a chemical element by its symbol or name (case-insensitive). For example: `element(\"H\")` or `element(\"hydrogen\")`.") +@description("Get properties of a chemical element by its symbol or name (case-insensitive).") +@example("element(\"H\")", "Get the entire element struct for hydrogen.") +@example("element(\"hydrogen\").ionization_energy", "Get the ionization energy of hydrogen.") fn element(pattern: String) -> ChemicalElement = _convert_from_raw(_get_chemical_element_data_raw(pattern)) diff --git a/numbat/modules/core/functions.nbt b/numbat/modules/core/functions.nbt index c088f693..a1ee5b76 100644 --- a/numbat/modules/core/functions.nbt +++ b/numbat/modules/core/functions.nbt @@ -2,64 +2,85 @@ use core::scalar @name("Identity function") @description("Return the input value.") +@example("id(8kg)") fn id(x: A) -> A = x @name("Absolute value") @description("Return the absolute value $|x|$ of the input. This works for quantities, too: `abs(-5 m) = 5 m`.") @url("https://doc.rust-lang.org/std/primitive.f64.html#method.abs") +# @example("abs(-22.2m)") fn abs(x: T) -> T @name("Square root") @description("Return the square root $\\sqrt\{x\}$ of the input: `sqrt(121 m^2) = 11 m`.") @url("https://en.wikipedia.org/wiki/Square_root") +@example("sqrt(4are) -> m") fn sqrt(x: D^2) -> D = x^(1/2) @name("Cube root") @description("Return the cube root $\\sqrt[3]\{x\}$ of the input: `cbrt(8 m^3) = 2 m`.") @url("https://en.wikipedia.org/wiki/Cube_root") +@example("cbrt(8l) -> cm") fn cbrt(x: D^3) -> D = x^(1/3) @name("Square function") @description("Return the square of the input, $x^2$: `sqr(5 m) = 25 m^2`.") +@example("sqr(7)") fn sqr(x: D) -> D^2 = x^2 @name("Rounding") @description("Round to the nearest integer. If the value is half-way between two integers, round away from $0$. See also: `round_in`.") @url("https://doc.rust-lang.org/std/primitive.f64.html#method.round") +@example("round(5.5)") +@example("round(-5.5)") fn round(x: Scalar) -> Scalar @name("Rounding") -@description("Round to the nearest multiple of `base`. For example: `round_in(m, 5.3 m) == 5 m`.") +@description("Round to the nearest multiple of `base`.") +@example("round_in(m, 5.3 m)", "Round in meters.") +@example("round_in(cm, 5.3 m)", "Round in centimeters.") fn round_in(base: D, value: D) -> D = round(value / base) × base @name("Floor function") @description("Returns the largest integer less than or equal to $x$. See also: `floor_in`.") @url("https://doc.rust-lang.org/std/primitive.f64.html#method.floor") +@example("floor(5.5)") fn floor(x: Scalar) -> Scalar @name("Floor function") -@description("Returns the largest integer multiple of `base` less than or equal to `value`. For example: `floor_in(m, 5.7 m) == 5 m`.") +@description("Returns the largest integer multiple of `base` less than or equal to `value`.") +@example("floor_in(m, 5.7 m)", "Floor in meters.") +@example("floor_in(cm, 5.7 m)", "Floor in centimeters.") fn floor_in(base: D, value: D) -> D = floor(value / base) × base @name("Ceil function") @description("Returns the smallest integer greater than or equal to $x$. See also: `ceil_in`.") @url("https://doc.rust-lang.org/std/primitive.f64.html#method.ceil") +@example("ceil(5.5)") fn ceil(x: Scalar) -> Scalar @name("Ceil function") -@description("Returns the smallest integer multuple of `base` greater than or equal to `value`. For example: `ceil_in(m, 5.3 m) == 6 m`.") +@description("Returns the smallest integer multuple of `base` greater than or equal to `value`.") +@example("ceil_in(m, 5.3 m)", "Ceil in meters.") +@example("ceil_in(cm, 5.3 m)", "Ceil in centimeters.") + fn ceil_in(base: D, value: D) -> D = ceil(value / base) × base @name("Truncation") @description("Returns the integer part of $x$. Non-integer numbers are always truncated towards zero. See also: `trunc_in`.") @url("https://doc.rust-lang.org/std/primitive.f64.html#method.trunc") +@example("trunc(5.5)") +@example("trunc(-5.5)") fn trunc(x: Scalar) -> Scalar @name("Truncation") -@description("Truncates to an integer multiple of `base` (towards zero). For example: `trunc_in(m, -5.7 m) == -5 m`.") +@description("Truncates to an integer multiple of `base` (towards zero).") +@example("trunc_in(m, 5.7 m)", "Truncate in meters.") +@example("trunc_in(cm, 5.7 m)", "Truncate in centimeters.") fn trunc_in(base: D, value: D) -> D = trunc(value / base) × base @name("Modulo") @description("Calculates the least nonnegative remainder of $a (\\mod b)$.") @url("https://doc.rust-lang.org/std/primitive.f64.html#method.rem_euclid") +@example("mod(27, 5)") fn mod(a: T, b: T) -> T diff --git a/numbat/modules/core/lists.nbt b/numbat/modules/core/lists.nbt index 8cd81b46..662383da 100644 --- a/numbat/modules/core/lists.nbt +++ b/numbat/modules/core/lists.nbt @@ -3,48 +3,60 @@ use core::error use core::strings @description("Get the length of a list") +@example("len([3, 2, 1])") fn len(xs: List) -> Scalar @description("Get the first element of a list. Yields a runtime error if the list is empty.") +@example("head([3, 2, 1])") fn head(xs: List) -> A @description("Get everything but the first element of a list. Yields a runtime error if the list is empty.") +@example("tail([3, 2, 1])") fn tail(xs: List) -> List @description("Prepend an element to a list") +@example("cons(77, [3, 2, 1])") fn cons(x: A, xs: List) -> List @description("Append an element to the end of a list") +@example("cons_end(77, [3, 2, 1])") fn cons_end(x: A, xs: List) -> List @description("Check if a list is empty") +@example("is_empty([3, 2, 1])") +@example("is_empty([])") fn is_empty(xs: List) -> Bool = xs == [] @description("Concatenate two lists") +@example("concat([3, 2, 1], [10, 11])") fn concat(xs1: List, xs2: List) -> List = if is_empty(xs1) then xs2 else cons(head(xs1), concat(tail(xs1), xs2)) @description("Get the first `n` elements of a list") +@example("take(2, [3, 2, 1, 0])") fn take(n: Scalar, xs: List) -> List = if n == 0 || is_empty(xs) then [] else cons(head(xs), take(n - 1, tail(xs))) @description("Get everything but the first `n` elements of a list") +@example("drop(2, [3, 2, 1, 0])") fn drop(n: Scalar, xs: List) -> List = if n == 0 || is_empty(xs) then xs else drop(n - 1, tail(xs)) @description("Get the element at index `i` in a list") +@example("element_at(2, [3, 2, 1, 0])") fn element_at(i: Scalar, xs: List) -> A = if i == 0 then head(xs) else element_at(i - 1, tail(xs)) @description("Generate a range of integer numbers from `start` to `end` (inclusive)") +@example("range(2, 12)") fn range(start: Scalar, end: Scalar) -> List = if start > end then [] @@ -52,18 +64,21 @@ fn range(start: Scalar, end: Scalar) -> List = @description("Reverse the order of a list") +@example("reverse([3, 2, 1])") fn reverse(xs: List) -> List = if is_empty(xs) then [] else cons_end(head(xs), reverse(tail(xs))) @description("Generate a new list by applying a function to each element of the input list") +@example("map(sqr, [3, 2, 1])", "Square all elements of a list.") fn map(f: Fn[(A) -> B], xs: List) -> List = if is_empty(xs) then [] else cons(f(head(xs)), map(f, tail(xs))) @description("Filter a list by a predicate") +@example("fn filter_fn(x) = x > 1\nfilter(filter_fn, [3, 2, 1, 0])", "Filter all elements greater than $1$.") fn filter(p: Fn[(A) -> Bool], xs: List) -> List = if is_empty(xs) then [] @@ -72,6 +87,7 @@ fn filter(p: Fn[(A) -> Bool], xs: List) -> List = else filter(p, tail(xs)) @description("Fold a function over a list") +@example("foldl(str_append, \"\", [\"Num\", \"bat\", \"!\"])", "Join a list of strings by folding.") fn foldl(f: Fn[(A, B) -> A], acc: A, xs: List) -> A = if is_empty(xs) then acc @@ -88,6 +104,7 @@ fn _merge(xs, ys, cmp) = @description("Sort a list of elements, using the given key function that maps the element to a quantity") +@example("fn map_fn(x) = mod(x, 10)\nsort_by_key(map_fn, [701, 313, 9999, 4])","Sort by last digit.") fn sort_by_key(key: Fn[(A) -> D], xs: List) -> List = if is_empty(xs) then [] @@ -98,9 +115,11 @@ fn sort_by_key(key: Fn[(A) -> D], xs: List) -> List = key) @description("Sort a list of quantities") +@example("sort([3, 2, 7, 8, -4, 0, -5])") fn sort(xs: List) -> List = sort_by_key(id, xs) @description("Add an element between each pair of elements in a list") +@example("intersperse(0, [1, 1, 1, 1])") fn intersperse(sep: A, xs: List) -> List = if is_empty(xs) then [] @@ -110,6 +129,7 @@ fn intersperse(sep: A, xs: List) -> List = fn _add(x, y) = x + y # TODO: replace this with a local function once we support them @description("Sum all elements of a list") +@example("sum([3, 2, 1])") fn sum(xs: List) -> D = foldl(_add, 0, xs) # TODO: implement linspace using `map` or similar once we have closures. This is ugly. @@ -119,12 +139,14 @@ fn _linspace_helper(start, end, n_steps, i) = else cons(start + (end - start) * i / (n_steps - 1), _linspace_helper(start, end, n_steps, i + 1)) @description("Generate a list of `n_steps` evenly spaced numbers from `start` to `end` (inclusive)") +@example("linspace(0, 10, 11)") fn linspace(start: D, end: D, n_steps: Scalar) -> List = if n_steps <= 1 then error("Number of steps must be larger than 1") else _linspace_helper(start, end, n_steps, 0) @description("Convert a list of strings into a single string by concatenating them with a separator") +@example("join([\"snake\", \"case\"], \"_\")") fn join(xs: List, sep: String) = if is_empty(xs) then "" @@ -133,6 +155,7 @@ fn join(xs: List, sep: String) = else "{head(xs)}{sep}{join(tail(xs), sep)}" @description("Split a string into a list of strings using a separator") +@example("split(\"Numbat is a statically typed programming language.\", \" \")") fn split(input: String, separator: String) -> List = if input == "" then [] diff --git a/numbat/modules/core/numbers.nbt b/numbat/modules/core/numbers.nbt index 2dba36c9..3265ea38 100644 --- a/numbat/modules/core/numbers.nbt +++ b/numbat/modules/core/numbers.nbt @@ -1,10 +1,16 @@ @description("Returns true if the input is `NaN`.") @url("https://doc.rust-lang.org/std/primitive.f64.html#method.is_nan") +@example("is_nan(37)") +@example("is_nan(NaN)") fn is_nan(n: T) -> Bool @description("Returns true if the input is positive infinity or negative infinity.") @url("https://doc.rust-lang.org/std/primitive.f64.html#method.is_infinite") +@example("is_infinite(37)") +@example("is_infinite(-inf)") fn is_infinite(n: T) -> Bool @description("Returns true if the input is neither infinite nor `NaN`.") +@example("is_finite(37)") +@example("is_finite(-inf)") fn is_finite(n: T) -> Bool = !is_nan(n) && !is_infinite(n) diff --git a/numbat/modules/core/quantities.nbt b/numbat/modules/core/quantities.nbt index c7cd9b07..3d886bd2 100644 --- a/numbat/modules/core/quantities.nbt +++ b/numbat/modules/core/quantities.nbt @@ -1,7 +1,9 @@ use core::scalar @description("Extract the unit of a quantity (the `km/h` in `20 km/h`). This can be useful in generic code, but should generally be avoided otherwise.") +@example("unit_of(20 km/h)") fn unit_of(x: T) -> T @description("Extract the plain value of a quantity (the `20` in `20 km/h`). This can be useful in generic code, but should generally be avoided otherwise.") +@example("value_of(20 km/h)") fn value_of(x: T) -> Scalar = x / unit_of(x) diff --git a/numbat/modules/core/strings.nbt b/numbat/modules/core/strings.nbt index fb1ef77b..609d1cf5 100644 --- a/numbat/modules/core/strings.nbt +++ b/numbat/modules/core/strings.nbt @@ -3,27 +3,35 @@ use core::functions use core::error @description("The length of a string") +@example("str_length(\"Numbat\")") fn str_length(s: String) -> Scalar @description("Subslice of a string") +@example("str_slice(\"Numbat\", 0, 2)") fn str_slice(s: String, start: Scalar, end: Scalar) -> String -@description("Get a single-character string from a Unicode code point. Example: `0x2764 -> chr`") +@description("Get a single-character string from a Unicode code point.") +@example("0x2764 -> chr") fn chr(n: Scalar) -> String -@description("Get the Unicode code point of the first character in a string. Example: `\"❤\" -> ord`") +@description("Get the Unicode code point of the first character in a string.") +@example("\"❤\" -> ord") fn ord(s: String) -> Scalar @description("Convert a string to lowercase") +@example("lowercase(\"Numbat\")") fn lowercase(s: String) -> String @description("Convert a string to uppercase") +@example("uppercase(\"Numbat\")") fn uppercase(s: String) -> String @description("Concatenate two strings") +@example("str_append(\"Numbat\",\"!\")") fn str_append(a: String, b: String) -> String = "{a}{b}" @description("Find the first occurrence of a substring in a string") +@example("str_find(\"Numbat is a statically typed programming language.\", \"typed\")") fn str_find(haystack: String, needle: String) -> Scalar = if len_haystack == 0 then -1 @@ -36,10 +44,12 @@ fn str_find(haystack: String, needle: String) -> Scalar = and tail_haystack = str_slice(haystack, 1, len_haystack) @description("Check if a string contains a substring") +@example("str_contains(\"Numbat is a statically typed programming language.\", \"typed\")") fn str_contains(haystack: String, needle: String) -> Bool = str_find(haystack, needle) != -1 @description("Replace all occurrences of a substring in a string") +@example("str_replace(\"Numbat is a statically typed programming language.\", \"statically typed programming language\", \"scientific calculator\")") fn str_replace(s: String, pattern: String, replacement: String) -> String = if pattern == "" then s @@ -50,6 +60,7 @@ fn str_replace(s: String, pattern: String, replacement: String) -> String = else s @description("Repeat the input string `n` times") +@example("str_repeat(\"abc\", 4)") fn str_repeat(a: String, n: Scalar) -> String = if n > 0 then str_append(a, str_repeat(a, n - 1)) @@ -76,7 +87,8 @@ fn _digit_in_base(base: Scalar, x: Scalar) -> String = # TODO: once we have anonymous functions / closures, we can implement base in a way # that it returns a partially-applied version of '_number_in_base'. This would allow # arbitrary 'x -> base(b)' conversions. -@description("Convert a number to the given base. Example: `42 |> base(16)`") +@description("Convert a number to the given base.") +@example("42 |> base(16)") fn base(b: Scalar, x: Scalar) -> String = if x < 0 then "-{base(b, -x)}" @@ -84,14 +96,18 @@ fn base(b: Scalar, x: Scalar) -> String = then _digit_in_base(b, x) else str_append(base(b, floor(x / b)), _digit_in_base(b, mod(x, b))) -@description("Get a binary representation of a number. Example: `42 -> bin`") +@description("Get a binary representation of a number.") +@example("42 -> bin") fn bin(x: Scalar) -> String = if x < 0 then "-{bin(-x)}" else "0b{base(2, x)}" -@description("Get an octal representation of a number. Example: `42 -> oct`") +@description("Get an octal representation of a number.") +@example("42 -> oct") fn oct(x: Scalar) -> String = if x < 0 then "-{oct(-x)}" else "0o{base(8, x)}" @description("Get a decimal representation of a number.") +@example("0b111 -> dec") fn dec(x: Scalar) -> String = base(10, x) -@description("Get a hexadecimal representation of a number. Example: `2^31-1 -> hex`") +@description("Get a hexadecimal representation of a number.") +@example("2^31-1 -> hex") fn hex(x: Scalar) -> String = if x < 0 then "-{hex(-x)}" else "0x{base(16, x)}" diff --git a/numbat/modules/datetime/functions.nbt b/numbat/modules/datetime/functions.nbt index fe9854ad..878e96c7 100644 --- a/numbat/modules/datetime/functions.nbt +++ b/numbat/modules/datetime/functions.nbt @@ -7,15 +7,22 @@ use units::time fn now() -> DateTime @description("Parses a string (date and time) into a `DateTime` object. See [here](./date-and-time.md#date-time-formats) for an overview of the supported formats.") +@example("datetime(\"2022-07-20T21:52+0200\")") +@example("datetime(\"2022-07-20 21:52 Europe/Berlin\")") +@example("datetime(\"2022/07/20 09:52 PM +0200\")") fn datetime(input: String) -> DateTime @description("Formats a `DateTime` object as a string.") +@example("format_datetime(\"This is a date in %B in the year %Y.\", datetime(\"2022-07-20 21:52 +0200\"))") fn format_datetime(format: String, input: DateTime) -> String @description("Returns the users local timezone.") +@example("get_local_timezone()") fn get_local_timezone() -> String @description("Returns a timezone conversion function, typically used with the conversion operator.") +@example("datetime(\"2022-07-20 21:52 +0200\") -> tz(\"Europe/Amsterdam\")") +@example("datetime(\"2022-07-20 21:52 +0200\") -> tz(\"Asia/Taipei\")") fn tz(tz: String) -> Fn[(DateTime) -> DateTime] @description("Timezone conversion function targeting the users local timezone (`datetime -> local`).") @@ -25,9 +32,11 @@ let local: Fn[(DateTime) -> DateTime] = tz(get_local_timezone()) let UTC: Fn[(DateTime) -> DateTime] = tz("UTC") @description("Converts a `DateTime` to a UNIX timestamp. Can be used on the right hand side of a conversion operator: `now() -> unixtime`.") +@example("datetime(\"2022-07-20 21:52 +0200\") -> unixtime") fn unixtime(input: DateTime) -> Scalar @description("Converts a UNIX timestamp to a `DateTime` object.") +@example("from_unixtime(2^31)") fn from_unixtime(input: Scalar) -> DateTime fn _today_str() = format_datetime("%Y-%m-%d", now()) @@ -36,12 +45,14 @@ fn _today_str() = format_datetime("%Y-%m-%d", now()) fn today() -> DateTime = datetime("{_today_str()} 00:00:00") @description("Parses a string (only date) into a `DateTime` object.") +@example("date(\"2022-07-20\")") fn date(input: String) -> DateTime = if str_contains(input, " ") then datetime(str_replace(input, " ", " 00:00:00 ")) else datetime("{input} 00:00:00") @description("Parses a string (time only) into a `DateTime` object.") +@example("time(\"21:52\")") fn time(input: String) -> DateTime = datetime("{_today_str()} {input}") @@ -50,6 +61,7 @@ fn _add_months(dt: DateTime, n_months: Scalar) -> DateTime fn _add_years(dt: DateTime, n_years: Scalar) -> DateTime @description("Adds the given time span to a `DateTime`. This uses leap-year and DST-aware calendar arithmetic with variable-length days, months, and years.") +@example("calendar_add(datetime(\"2022-07-20 21:52 +0200\"), 2 years)") fn calendar_add(dt: DateTime, span: Time) -> DateTime = if span_unit == days then _add_days(dt, span / days) @@ -65,14 +77,17 @@ fn calendar_add(dt: DateTime, span: Time) -> DateTime = span_unit = unit_of(span) @description("Subtract the given time span from a `DateTime`. This uses leap-year and DST-aware calendar arithmetic with variable-length days, months, and years.") +@example("calendar_sub(datetime(\"2022-07-20 21:52 +0200\"), 3 years)") fn calendar_sub(dt: DateTime, span: Time) -> DateTime = calendar_add(dt, -span) @description("Get the day of the week from a given `DateTime`.") +@example("weekday(datetime(\"2022-07-20 21:52 +0200\"))") fn weekday(dt: DateTime) -> String = format_datetime("%A", dt) @name("Julian date") @description("Convert a `DateTime` to a Julian date, the number of days since the origin of the Julian date system (noon on November 24, 4714 BC in the proleptic Gregorian calendar).") @url("https://en.wikipedia.org/wiki/Julian_day") +@example("julian_date(datetime(\"2022-07-20 21:52 +0200\"))") fn julian_date(dt: DateTime) -> Time = (dt - datetime("-4713-11-24 12:00:00 +0000")) -> days diff --git a/numbat/modules/datetime/human.nbt b/numbat/modules/datetime/human.nbt index c4b1a282..e6701e99 100644 --- a/numbat/modules/datetime/human.nbt +++ b/numbat/modules/datetime/human.nbt @@ -33,6 +33,7 @@ fn _human_readable_duration(time: Time, dt: DateTime, num_days: Scalar) -> Strin @name("Human-readable time duration") @url("https://numbat.dev/doc/date-and-time.html") @description("Converts a time duration to a human-readable string in days, hours, minutes and seconds.") +@example("century/1e6 -> human", "How long is a microcentury?") fn human(time: Time) = if _human_num_days(time) > 1000 then "{_human_num_days(time)} days" diff --git a/numbat/modules/extra/algebra.nbt b/numbat/modules/extra/algebra.nbt index 60e034d1..fd7bccf3 100644 --- a/numbat/modules/extra/algebra.nbt +++ b/numbat/modules/extra/algebra.nbt @@ -7,6 +7,7 @@ fn _qe_solution(a: A, b: B, c: B² / A, sign: Scalar) -> B / A = @name("Solve quadratic equations") @url("https://en.wikipedia.org/wiki/Quadratic_equation") @description("Returns the solutions of the equation a x² + b x + c = 0") +@example("quadratic_equation(2, -1, -1)", "Solve the equation $2x² -x -1 = 0$") fn quadratic_equation(a: A, b: B, c: B² / A) -> List = if a == 0 then if b == 0 diff --git a/numbat/modules/extra/color.nbt b/numbat/modules/extra/color.nbt index 6b50c20a..89af9e94 100644 --- a/numbat/modules/extra/color.nbt +++ b/numbat/modules/extra/color.nbt @@ -9,10 +9,12 @@ struct Color { } @description("Create a `Color` from RGB (red, green, blue) values in the range $[0, 256)$.") +@example("rgb(125, 128, 218)") fn rgb(red: Scalar, green: Scalar, blue: Scalar) -> Color = Color { red: red, green: green, blue: blue } -@description("Create a `Color` from a (hexadecimal) value, e.g. `color(0xff7700)`") +@description("Create a `Color` from a (hexadecimal) value.") +@example("color(0xff7700)") fn color(rgb_hex: Scalar) -> Color = rgb( floor(rgb_hex / 256^2), @@ -22,15 +24,18 @@ fn color(rgb_hex: Scalar) -> Color = fn _color_to_scalar(color: Color) -> Scalar = color.red * 0x010000 + color.green * 0x000100 + color.blue -@description("Convert a color to its RGB representation, e.g. `cyan -> color_rgb`") +@description("Convert a color to its RGB representation.") +@example("cyan -> color_rgb") fn color_rgb(color: Color) -> String = "rgb({color.red}, {color.green}, {color.blue})" -@description("Convert a color to its RGB floating point representation, e.g. `cyan -> color_rgb_float`") +@description("Convert a color to its RGB floating point representation.") +@example("cyan -> color_rgb_float") fn color_rgb_float(color: Color) -> String = "rgb({color.red / 255:.3}, {color.green / 255:.3}, {color.blue / 255:.3})" -@description("Convert a color to its hexadecimal representation, e.g. `rgb(225, 36, 143) -> color_hex`") +@description("Convert a color to its hexadecimal representation.") +@example("rgb(225, 36, 143) -> color_hex") fn color_hex(color: Color) -> String = str_append("#", str_replace(str_replace("{color -> _color_to_scalar -> hex:>8}", "0x", ""), " ", "0")) diff --git a/numbat/modules/math/geometry.nbt b/numbat/modules/math/geometry.nbt index e2029e20..57b09932 100644 --- a/numbat/modules/math/geometry.nbt +++ b/numbat/modules/math/geometry.nbt @@ -2,9 +2,11 @@ use core::functions use math::constants @description("The length of the hypotenuse of a right-angled triangle $\\sqrt\{x^2+y^2\}$.") +@example("hypot2(3, 4)") fn hypot2(x: T, y: T) -> T = sqrt(x^2 + y^2) @description("The Euclidean norm of a 3D vector $\\sqrt\{x^2+y^2+z^2\}$.") +@example("hypot3(4, 1, 4)") fn hypot3(x: T, y: T, z: T) -> T = sqrt(x^2 + y^2 + z^2) # The following functions use a generic dimension instead of diff --git a/numbat/modules/math/number_theory.nbt b/numbat/modules/math/number_theory.nbt index e3d45420..1bef78c7 100644 --- a/numbat/modules/math/number_theory.nbt +++ b/numbat/modules/math/number_theory.nbt @@ -4,6 +4,7 @@ use core::functions @name("Greatest common divisor") @description("The largest positive integer that divides each of the integers $a$ and $b$.") @url("https://en.wikipedia.org/wiki/Greatest_common_divisor") +@example("gcd(60,42)") fn gcd(a: Scalar, b: Scalar) -> Scalar = if b == 0 then abs(a) @@ -12,4 +13,5 @@ fn gcd(a: Scalar, b: Scalar) -> Scalar = @name("Least common multiple") @description("The smallest positive integer that is divisible by both $a$ and $b$.") @url("https://en.wikipedia.org/wiki/Least_common_multiple") +@example("lcm(14, 4)") fn lcm(a: Scalar, b: Scalar) -> Scalar = abs(a * b) / gcd(a, b) diff --git a/numbat/modules/math/statistics.nbt b/numbat/modules/math/statistics.nbt index 293cb076..c99d3e22 100644 --- a/numbat/modules/math/statistics.nbt +++ b/numbat/modules/math/statistics.nbt @@ -5,38 +5,44 @@ fn _max(x: D, y: D) -> D = if x > y then x else y fn _min(x: D, y: D) -> D = if x < y then x else y @name("Maxmimum") -@description("Get the largest element of a list: `maximum([30 cm, 2 m]) = 2 m`.") +@description("Get the largest element of a list.") +@example("maximum([30 cm, 2 m])") fn maximum(xs: List) -> D = if len(xs) == 1 then head(xs) else _max(head(xs), maximum(tail(xs))) @name("Minimum") -@description("Get the smallest element of a list: `minimum([30 cm, 2 m]) = 30 cm`.") +@description("Get the smallest element of a list.") +@example("minimum([30 cm, 2 m])") fn minimum(xs: List) -> D = if len(xs) == 1 then head(xs) else _min(head(xs), minimum(tail(xs))) @name("Arithmetic mean") -@description("Calculate the arithmetic mean of a list of quantities: `mean([1 m, 2 m, 300 cm]) = 2 m`.") +@description("Calculate the arithmetic mean of a list of quantities.") +@example("mean([1 m, 2 m, 300 cm])") @url("https://en.wikipedia.org/wiki/Arithmetic_mean") fn mean(xs: List) -> D = if is_empty(xs) then 0 else sum(xs) / len(xs) @name("Variance") @url("https://en.wikipedia.org/wiki/Variance") @description("Calculate the population variance of a list of quantities") +@example("variance([1 m, 2 m, 300 cm])") fn variance(xs: List) -> D^2 = mean(map(sqr, xs)) - sqr(mean(xs)) @name("Standard deviation") @url("https://en.wikipedia.org/wiki/Standard_deviation") @description("Calculate the population standard deviation of a list of quantities") +@example("stdev([1 m, 2 m, 300 cm])") fn stdev(xs: List) -> D = sqrt(variance(xs)) @name("Median") @url("https://en.wikipedia.org/wiki/Median") @description("Calculate the median of a list of quantities") +@example("median([1 m, 2 m, 400 cm])") fn median(xs: List) -> D = # TODO: this is extremely inefficient if mod(n, 2) == 1 then element_at((n - 1) / 2, sort(xs)) diff --git a/numbat/modules/math/transcendental.nbt b/numbat/modules/math/transcendental.nbt index f079c78f..6e838e8e 100644 --- a/numbat/modules/math/transcendental.nbt +++ b/numbat/modules/math/transcendental.nbt @@ -3,26 +3,31 @@ use core::scalar @name("Exponential function") @description("The exponential function, $e^x$.") @url("https://en.wikipedia.org/wiki/Exponential_function") +@example("exp(4)") fn exp(x: Scalar) -> Scalar @name("Natural logarithm") @description("The natural logarithm with base $e$.") @url("https://en.wikipedia.org/wiki/Natural_logarithm") +@example("ln(20)") fn ln(x: Scalar) -> Scalar @name("Natural logarithm") @description("The natural logarithm with base $e$.") @url("https://en.wikipedia.org/wiki/Natural_logarithm") +@example("log(20)") fn log(x: Scalar) -> Scalar = ln(x) @name("Common logarithm") @description("The common logarithm with base $10$.") @url("https://en.wikipedia.org/wiki/Common_logarithm") +@example("log10(100)") fn log10(x: Scalar) -> Scalar @name("Binary logarithm") @description("The binary logarithm with base $2$.") @url("https://en.wikipedia.org/wiki/Binary_logarithm") +@example("log2(256)") fn log2(x: Scalar) -> Scalar @name("Gamma function") diff --git a/numbat/modules/numerics/diff.nbt b/numbat/modules/numerics/diff.nbt index 63c3c87b..e96ca391 100644 --- a/numbat/modules/numerics/diff.nbt +++ b/numbat/modules/numerics/diff.nbt @@ -3,6 +3,7 @@ use core::quantities @name("Numerical differentiation") @url("https://en.wikipedia.org/wiki/Numerical_differentiation") @description("Compute the numerical derivative of the function $f$ at point $x$ using the central difference method.") +@example("fn polynomial(x) = x² -x -1\ndiff(polynomial, 1)", "Compute the drivative of $f(x) = x² -x -1$ at $x=1$.") fn diff(f: Fn[(X) -> Y], x: X) -> Y / X = (f(x + Δx) - f(x - Δx)) / 2 Δx where diff --git a/numbat/modules/numerics/fixed_point.nbt b/numbat/modules/numerics/fixed_point.nbt index a046c9e9..8ee9e978 100644 --- a/numbat/modules/numerics/fixed_point.nbt +++ b/numbat/modules/numerics/fixed_point.nbt @@ -15,5 +15,6 @@ fn _fixed_point(f: Fn[(X) -> X], x0: X, ε: X, max_iter: Scalar) = @name("Fixed-point iteration") @url("https://en.wikipedia.org/wiki/Fixed-point_iteration") @description("Compute the approximate fixed point of a function $f: X \\rightarrow X$ starting from $x_0$, until $|f(x) - x| < ε$.") +@example("fn function(x) = x/2 - 1\nfixed_point(function, 0, 0.01)", "Compute the fixed poin of $f(x) = x/2 -1$.") fn fixed_point(f: Fn[(X) -> X], x0: X, ε: X) = _fixed_point(f, x0, ε, 100) diff --git a/numbat/modules/numerics/solve.nbt b/numbat/modules/numerics/solve.nbt index 7335a39b..6bd5703b 100644 --- a/numbat/modules/numerics/solve.nbt +++ b/numbat/modules/numerics/solve.nbt @@ -4,6 +4,7 @@ use core::error @name("Bisection method") @url("https://en.wikipedia.org/wiki/Bisection_method") @description("Find the root of the function $f$ in the interval $[x_1, x_2]$ using the bisection method. The function $f$ must be continuous and $f(x_1) \cdot f(x_2) < 0$.") +@example("fn f(x) = x² +x -2\nroot_bisect(f, 0, 100, 0.01, 0.01)", "Find the root of $f(x) = x² +x -2$ in the interval $[0, 100]$.") fn root_bisect(f: Fn[(X) -> Y], x1: X, x2: X, x_tol: X, y_tol: Y) -> X = if abs(x1 - x2) < x_tol then x_mean @@ -27,5 +28,6 @@ fn _root_newton_helper(f: Fn[(X) -> Y], f_prime: Fn[(X) -> Y / X @name("Newton's method") @url("https://en.wikipedia.org/wiki/Newton%27s_method") @description("Find the root of the function $f(x)$ and its derivative $f'(x)$ using Newton's method.") +@example("fn f(x) = x² -3x +2\nfn f_prime(x) = 2x -3\nroot_newton(f, f_prime, 0 , 0.01)", "Find a root of $f(x) = x² -3x +2$ using Newton's method.") fn root_newton(f: Fn[(X) -> Y], f_prime: Fn[(X) -> Y / X], x0: X, y_tol: Y) -> X = _root_newton_helper(f, f_prime, x0, y_tol, 10_000) diff --git a/numbat/modules/physics/temperature_conversion.nbt b/numbat/modules/physics/temperature_conversion.nbt index 8dac933d..89a2bc16 100644 --- a/numbat/modules/physics/temperature_conversion.nbt +++ b/numbat/modules/physics/temperature_conversion.nbt @@ -5,10 +5,12 @@ use units::si let _offset_celsius = 273.15 @description("Converts from degree Celsius (°C) to Kelvin.") +@example("from_celsius(300)", "$300 °C$ in Kelvin.") @url("https://en.wikipedia.org/wiki/Conversion_of_scales_of_temperature") fn from_celsius(t_celsius: Scalar) -> Temperature = (t_celsius + _offset_celsius) kelvin @description("Converts from Kelvin to degree Celcius (°C). This can be used on the right hand side of a conversion operator: `200 K -> celsius`.") +@example("300K -> celsius", "$300K$ in degree Celsius.") @url("https://en.wikipedia.org/wiki/Conversion_of_scales_of_temperature") fn celsius(t_kelvin: Temperature) -> Scalar = t_kelvin / kelvin - _offset_celsius @@ -16,9 +18,11 @@ let _offset_fahrenheit = 459.67 let _scale_fahrenheit = 5 / 9 @description("Converts from degree Fahrenheit (°F) to Kelvin.") +@example("from_fahrenheit(300)", "$300 °F$ in Kelvin.") @url("https://en.wikipedia.org/wiki/Conversion_of_scales_of_temperature") fn from_fahrenheit(t_fahrenheit: Scalar) -> Temperature = ((t_fahrenheit + _offset_fahrenheit) × _scale_fahrenheit) kelvin @description("Converts from Kelvin to degree Fahrenheit (°F). This can be used on the right hand side of a conversion operator: `200 K -> fahrenheit`.") +@example("300K -> fahrenheit", "$300K$ in degree Fahrenheit.") @url("https://en.wikipedia.org/wiki/Conversion_of_scales_of_temperature") fn fahrenheit(t_kelvin: Temperature) -> Scalar = (t_kelvin / kelvin) / _scale_fahrenheit - _offset_fahrenheit diff --git a/numbat/modules/units/mixed.nbt b/numbat/modules/units/mixed.nbt index 8ef93e26..9b688cf3 100644 --- a/numbat/modules/units/mixed.nbt +++ b/numbat/modules/units/mixed.nbt @@ -5,11 +5,13 @@ use units::imperial @name("Degrees, minutes, seconds") @description("Convert an angle to a mixed degrees, (arc)minutes, and (arc)seconds representation. Also called sexagesimal degree notation.") @url("https://en.wikipedia.org/wiki/Sexagesimal_degree") +@example("DMS(46.5858°)") fn DMS(alpha: Angle) -> String = _mixed_units(alpha, [deg, arcmin, arcsec], ["° ", "′ ", "″"], true) @name("Degrees, decimal minutes") @description("Convert an angle to a mixed degrees and decimal minutes representation.") +@example("DM(46.5858°)") @url("https://en.wikipedia.org/wiki/Decimal_degrees") fn DM(alpha: Angle) -> String = _mixed_units(alpha, [deg, arcmin], ["° ", "′"], false) @@ -17,11 +19,13 @@ fn DM(alpha: Angle) -> String = @name("Feet and inches") @description("Convert a length to a mixed feet and inches representation.") @url("https://en.wikipedia.org/wiki/Foot_(unit)") +@example("feet_and_inches(180cm)") fn feet_and_inches(length: Length) -> String = _mixed_units(length, [foot, inch], [" ft ", " in"], false) @name("Pounds and ounces") @description("Convert a mass to a mixed pounds and ounces representation.") @url("https://en.wikipedia.org/wiki/Pound_(mass)") +@example("pounds_and_ounces(1kg)") fn pounds_and_ounces(mass: Mass) -> String = _mixed_units(mass, [pound, ounce], [" lb ", " oz"], false) From f6dd12a919aa4f5f721399355ab6b69d1cd12a65 Mon Sep 17 00:00:00 2001 From: Bzero Date: Mon, 16 Sep 2024 19:32:03 +0200 Subject: [PATCH 4/9] Move details closing tag inside conditional --- book/src/list-functions-datetime.md | 6 +- book/src/list-functions-math.md | 86 ---------------- book/src/list-functions-other.md | 2 - numbat/examples/inspect.rs | 150 ++++++++++++++-------------- 4 files changed, 76 insertions(+), 168 deletions(-) diff --git a/book/src/list-functions-datetime.md b/book/src/list-functions-datetime.md index d43ad85b..5f763182 100644 --- a/book/src/list-functions-datetime.md +++ b/book/src/list-functions-datetime.md @@ -11,8 +11,6 @@ Returns the current date and time. fn now() -> DateTime ``` - - ### `datetime` Parses a string (date and time) into a `DateTime` object. See [here](./date-and-time.md#date-time-formats) for an overview of the supported formats. @@ -182,8 +180,6 @@ Returns the current date at midnight (in the local time). fn today() -> DateTime ``` - - ### `date` Parses a string (only date) into a `DateTime` object. @@ -223,7 +219,7 @@ fn time(input: String) -> DateTime time("21:52") - = 2024-09-15 21:52:00 UTC [DateTime] + = 2024-09-16 21:52:00 UTC [DateTime] ``` diff --git a/book/src/list-functions-math.md b/book/src/list-functions-math.md index 891d1bfb..8849b265 100644 --- a/book/src/list-functions-math.md +++ b/book/src/list-functions-math.md @@ -36,8 +36,6 @@ More information [here](https://doc.rust-lang.org/std/primitive.f64.html#method. fn abs(x: T) -> T ``` - - ### `sqrt` (Square root) Return the square root \\( \sqrt{x} \\) of the input: `sqrt(121 m^2) = 11 m`. More information [here](https://en.wikipedia.org/wiki/Square_root). @@ -504,8 +502,6 @@ More information [here](https://en.wikipedia.org/wiki/Gamma_function). fn gamma(x: Scalar) -> Scalar ``` - - ## Trigonometry Defined in: `math::trigonometry` @@ -517,8 +513,6 @@ More information [here](https://en.wikipedia.org/wiki/Trigonometric_functions). fn sin(x: Scalar) -> Scalar ``` - - ### `cos` (Cosine) More information [here](https://en.wikipedia.org/wiki/Trigonometric_functions). @@ -526,8 +520,6 @@ More information [here](https://en.wikipedia.org/wiki/Trigonometric_functions). fn cos(x: Scalar) -> Scalar ``` - - ### `tan` (Tangent) More information [here](https://en.wikipedia.org/wiki/Trigonometric_functions). @@ -535,8 +527,6 @@ More information [here](https://en.wikipedia.org/wiki/Trigonometric_functions). fn tan(x: Scalar) -> Scalar ``` - - ### `asin` (Arc sine) More information [here](https://en.wikipedia.org/wiki/Inverse_trigonometric_functions). @@ -544,8 +534,6 @@ More information [here](https://en.wikipedia.org/wiki/Inverse_trigonometric_func fn asin(x: Scalar) -> Scalar ``` - - ### `acos` (Arc cosine) More information [here](https://en.wikipedia.org/wiki/Inverse_trigonometric_functions). @@ -553,8 +541,6 @@ More information [here](https://en.wikipedia.org/wiki/Inverse_trigonometric_func fn acos(x: Scalar) -> Scalar ``` - - ### `atan` (Arc tangent) More information [here](https://en.wikipedia.org/wiki/Inverse_trigonometric_functions). @@ -562,8 +548,6 @@ More information [here](https://en.wikipedia.org/wiki/Inverse_trigonometric_func fn atan(x: Scalar) -> Scalar ``` - - ### `atan2` More information [here](https://en.wikipedia.org/wiki/Atan2). @@ -571,8 +555,6 @@ More information [here](https://en.wikipedia.org/wiki/Atan2). fn atan2(y: T, x: T) -> Scalar ``` - - ### `sinh` (Hyperbolic sine) More information [here](https://en.wikipedia.org/wiki/Hyperbolic_functions). @@ -580,8 +562,6 @@ More information [here](https://en.wikipedia.org/wiki/Hyperbolic_functions). fn sinh(x: Scalar) -> Scalar ``` - - ### `cosh` (Hyperbolic cosine) More information [here](https://en.wikipedia.org/wiki/Hyperbolic_functions). @@ -589,8 +569,6 @@ More information [here](https://en.wikipedia.org/wiki/Hyperbolic_functions). fn cosh(x: Scalar) -> Scalar ``` - - ### `tanh` (Hyperbolic tangent) More information [here](https://en.wikipedia.org/wiki/Hyperbolic_functions). @@ -598,8 +576,6 @@ More information [here](https://en.wikipedia.org/wiki/Hyperbolic_functions). fn tanh(x: Scalar) -> Scalar ``` - - ### `asinh` (Area hyperbolic sine) More information [here](https://en.wikipedia.org/wiki/Hyperbolic_functions). @@ -607,8 +583,6 @@ More information [here](https://en.wikipedia.org/wiki/Hyperbolic_functions). fn asinh(x: Scalar) -> Scalar ``` - - ### `acosh` (Area hyperbolic cosine) More information [here](https://en.wikipedia.org/wiki/Hyperbolic_functions). @@ -616,8 +590,6 @@ More information [here](https://en.wikipedia.org/wiki/Hyperbolic_functions). fn acosh(x: Scalar) -> Scalar ``` - - ### `atanh` (Area hyperbolic tangent ) More information [here](https://en.wikipedia.org/wiki/Hyperbolic_functions). @@ -625,8 +597,6 @@ More information [here](https://en.wikipedia.org/wiki/Hyperbolic_functions). fn atanh(x: Scalar) -> Scalar ``` - - ## Statistics Defined in: `math::statistics` @@ -778,8 +748,6 @@ Uniformly samples the interval \\( [0,1) \\). fn random() -> Scalar ``` - - ### `rand_uniform` (Continuous uniform distribution sampling) Uniformly samples the interval \\( [a,b) \\) if \\( a \le b \\) or \\( [b,a) \\) if \\( b(a: T, b: T) -> T ``` - - ### `rand_int` (Discrete uniform distribution sampling) Uniformly samples integers from the interval \\( [a, b] \\). More information [here](https://en.wikipedia.org/wiki/Discrete_uniform_distribution). @@ -798,8 +764,6 @@ More information [here](https://en.wikipedia.org/wiki/Discrete_uniform_distribut fn rand_int(a: Scalar, b: Scalar) -> Scalar ``` - - ### `rand_bernoulli` (Bernoulli distribution sampling) Samples a Bernoulli random variable. That is, \\( 1 \\) with probability \\( p \\) and \\( 0 \\) with probability \\( 1-p \\). The parameter \\( p \\) must be a probability (\\( 0 \le p \le 1 \\)). More information [here](https://en.wikipedia.org/wiki/Bernoulli_distribution). @@ -808,8 +772,6 @@ More information [here](https://en.wikipedia.org/wiki/Bernoulli_distribution). fn rand_bernoulli(p: Scalar) -> Scalar ``` - - ### `rand_binom` (Binomial distribution sampling) Samples a binomial distribution by doing \\( n \\) Bernoulli trials with probability \\( p \\). The parameter \\( n \\) must be a positive integer, the parameter \\( p \\) must be a probability (\\( 0 \le p \le 1 \\)). @@ -819,8 +781,6 @@ More information [here](https://en.wikipedia.org/wiki/Binomial_distribution). fn rand_binom(n: Scalar, p: Scalar) -> Scalar ``` - - ### `rand_norm` (Normal distribution sampling) Samples a normal distribution with mean \\( \mu \\) and standard deviation \\( \sigma \\) using the Box-Muller transform. More information [here](https://en.wikipedia.org/wiki/Normal_distribution). @@ -829,8 +789,6 @@ More information [here](https://en.wikipedia.org/wiki/Normal_distribution). fn rand_norm(μ: T, σ: T) -> T ``` - - ### `rand_geom` (Geometric distribution sampling) Samples a geometric distribution (the distribution of the number of Bernoulli trials with probability \\( p \\) needed to get one success) by inversion sampling. The parameter \\( p \\) must be a probability (\\( 0 \le p \le 1 \\)). More information [here](https://en.wikipedia.org/wiki/Geometric_distribution). @@ -839,8 +797,6 @@ More information [here](https://en.wikipedia.org/wiki/Geometric_distribution). fn rand_geom(p: Scalar) -> Scalar ``` - - ### `rand_poisson` (Poisson distribution sampling) Sampling a poisson distribution with rate \\( \lambda \\), that is, the distribution of the number of events occurring in a fixed interval if these events occur with mean rate \\( \lambda \\). The rate parameter \\( \lambda \\) must be non-negative. More information [here](https://en.wikipedia.org/wiki/Poisson_distribution). @@ -849,8 +805,6 @@ More information [here](https://en.wikipedia.org/wiki/Poisson_distribution). fn rand_poisson(λ: Scalar) -> Scalar ``` - - ### `rand_expon` (Exponential distribution sampling) Sampling an exponential distribution (the distribution of the distance between events in a Poisson process with rate \\( \lambda \\)) using inversion sampling. The rate parameter \\( \lambda \\) must be positive. More information [here](https://en.wikipedia.org/wiki/Exponential_distribution). @@ -859,8 +813,6 @@ More information [here](https://en.wikipedia.org/wiki/Exponential_distribution). fn rand_expon(λ: T) -> 1 / T ``` - - ### `rand_lognorm` (Log-normal distribution sampling) Sampling a log-normal distribution, that is, a distribution whose logarithm is a normal distribution with mean \\( \mu \\) and standard deviation \\( \sigma \\). More information [here](https://en.wikipedia.org/wiki/Log-normal_distribution). @@ -869,8 +821,6 @@ More information [here](https://en.wikipedia.org/wiki/Log-normal_distribution). fn rand_lognorm(μ: Scalar, σ: Scalar) -> Scalar ``` - - ### `rand_pareto` (Pareto distribution sampling) Sampling a Pareto distribution with minimum value `min` and shape parameter \\( \alpha \\) using inversion sampling. Both parameters must be positive. More information [here](https://en.wikipedia.org/wiki/Pareto_distribution). @@ -879,8 +829,6 @@ More information [here](https://en.wikipedia.org/wiki/Pareto_distribution). fn rand_pareto(α: Scalar, min: T) -> T ``` - - ## Number theory Defined in: `math::number_theory` @@ -1101,8 +1049,6 @@ The area of a circle, \\( \pi r^2 \\). fn circle_area(radius: L) -> L^2 ``` - - ### `circle_circumference` The circumference of a circle, \\( 2\pi r \\). @@ -1110,8 +1056,6 @@ The circumference of a circle, \\( 2\pi r \\). fn circle_circumference(radius: L) -> L ``` - - ### `sphere_area` The surface area of a sphere, \\( 4\pi r^2 \\). @@ -1119,8 +1063,6 @@ The surface area of a sphere, \\( 4\pi r^2 \\). fn sphere_area(radius: L) -> L^2 ``` - - ### `sphere_volume` The volume of a sphere, \\( \frac{4}{3}\pi r^3 \\). @@ -1128,8 +1070,6 @@ The volume of a sphere, \\( \frac{4}{3}\pi r^3 \\). fn sphere_volume(radius: L) -> L^3 ``` - - ## Algebra Defined in: `extra::algebra` @@ -1168,101 +1108,75 @@ Defined in: `math::trigonometry_extra` fn cot(x: Scalar) -> Scalar ``` - - ### `acot` ```nbt fn acot(x: Scalar) -> Scalar ``` - - ### `coth` ```nbt fn coth(x: Scalar) -> Scalar ``` - - ### `acoth` ```nbt fn acoth(x: Scalar) -> Scalar ``` - - ### `secant` ```nbt fn secant(x: Scalar) -> Scalar ``` - - ### `arcsecant` ```nbt fn arcsecant(x: Scalar) -> Scalar ``` - - ### `cosecant` ```nbt fn cosecant(x: Scalar) -> Scalar ``` - - ### `csc` ```nbt fn csc(x: Scalar) -> Scalar ``` - - ### `acsc` ```nbt fn acsc(x: Scalar) -> Scalar ``` - - ### `sech` ```nbt fn sech(x: Scalar) -> Scalar ``` - - ### `asech` ```nbt fn asech(x: Scalar) -> Scalar ``` - - ### `csch` ```nbt fn csch(x: Scalar) -> Scalar ``` - - ### `acsch` ```nbt fn acsch(x: Scalar) -> Scalar ``` - - diff --git a/book/src/list-functions-other.md b/book/src/list-functions-other.md index 90363f6f..ef5173d1 100644 --- a/book/src/list-functions-other.md +++ b/book/src/list-functions-other.md @@ -13,8 +13,6 @@ Throw an error with the specified message. Stops the execution of the program. fn error(message: String) -> T ``` - - ## Floating point Defined in: `core::numbers` diff --git a/numbat/examples/inspect.rs b/numbat/examples/inspect.rs index 74f65c67..f1fe019c 100644 --- a/numbat/examples/inspect.rs +++ b/numbat/examples/inspect.rs @@ -84,94 +84,94 @@ fn inspect_functions_in_module(ctx: &Context, module: String) { println!("
"); println!("Examples"); println!(); - } - - for (example_code, example_description) in examples { - let mut example_ctx = prepare_context(); - let _result = example_ctx - .interpret("use prelude", CodeSource::Internal) - .unwrap(); - - let extra_import = if !example_ctx - .resolver() - .imported_modules - .contains(&module_path) - { - format!("use {}\n", module) - } else { - "".into() - }; - let _result = example_ctx - .interpret(&extra_import, CodeSource::Internal) - .unwrap(); - - if let Ok((statements, results)) = - example_ctx.interpret(&example_code, CodeSource::Internal) - { - //Format the example input - let example_input = format!(">>> {}", example_code); - - //Encode the example url - let url_code = extra_import + &example_code; - let example_url = format!( - "https://numbat.dev/?q={}", - percent_encoding::utf8_percent_encode( - &url_code, - percent_encoding::NON_ALPHANUMERIC - ) - ); - - //Assemble the example output - let mut example_output = String::new(); - example_output += "\n"; - - for statement in &statements { - example_output += &plain_text_format(&statement.pretty_print(), true); - example_output += "\n\n"; - } - let result_markup = results.to_markup( - statements.last(), - &example_ctx.dimension_registry(), - true, - true, - ); - example_output += &plain_text_format(&result_markup, false); + for (example_code, example_description) in examples { + let mut example_ctx = prepare_context(); + let _result = example_ctx + .interpret("use prelude", CodeSource::Internal) + .unwrap(); + + let extra_import = if !example_ctx + .resolver() + .imported_modules + .contains(&module_path) + { + format!("use {}\n", module) + } else { + "".into() + }; + let _result = example_ctx + .interpret(&extra_import, CodeSource::Internal) + .unwrap(); + + if let Ok((statements, results)) = + example_ctx.interpret(&example_code, CodeSource::Internal) + { + //Format the example input + let example_input = format!(">>> {}", example_code); + + //Encode the example url + let url_code = extra_import + &example_code; + let example_url = format!( + "https://numbat.dev/?q={}", + percent_encoding::utf8_percent_encode( + &url_code, + percent_encoding::NON_ALPHANUMERIC + ) + ); - if results.is_value() { + //Assemble the example output + let mut example_output = String::new(); example_output += "\n"; - } - //Print the example - if let Some(example_description) = example_description { - println!( + for statement in &statements { + example_output += &plain_text_format(&statement.pretty_print(), true); + example_output += "\n\n"; + } + + let result_markup = results.to_markup( + statements.last(), + &example_ctx.dimension_registry(), + true, + true, + ); + example_output += &plain_text_format(&result_markup, false); + + if results.is_value() { + example_output += "\n"; + } + + //Print the example + if let Some(example_description) = example_description { + println!( "* {}\n\n Run this example", replace_equation_delimiters(example_description), example_url ); + } else { + println!( + "* Run this example\n", + example_url + ); + } + + println!(" ```nbt"); + for l in example_input.lines() { + println!(" {}", l); + } + for l in example_output.lines() { + println!(" {}", l); + } + println!(" ```"); } else { - println!( - "* Run this example\n", - example_url - ); - } - - println!(" ```nbt"); - for l in example_input.lines() { - println!(" {}", l); - } - for l in example_output.lines() { - println!(" {}", l); - } - println!(" ```"); - } else { - eprintln!( + eprintln!( "Warning: Example \"{example_code}\" of function {fn_name} did not run successfully." ); + } } + println!("
"); + println!(); } - println!(""); - println!(); } } From b32bb203d133f04c707d2d7d9dd7d8c14b4e0fa6 Mon Sep 17 00:00:00 2001 From: Bzero Date: Tue, 24 Sep 2024 16:33:05 +0200 Subject: [PATCH 5/9] Remove example for the time function --- book/src/list-functions-datetime.md | 15 --------------- numbat/modules/datetime/functions.nbt | 1 - 2 files changed, 16 deletions(-) diff --git a/book/src/list-functions-datetime.md b/book/src/list-functions-datetime.md index 5f763182..ebedccc8 100644 --- a/book/src/list-functions-datetime.md +++ b/book/src/list-functions-datetime.md @@ -209,21 +209,6 @@ Parses a string (time only) into a `DateTime` object. fn time(input: String) -> DateTime ``` -
-Examples - -* Run this example - - ```nbt - >>> time("21:52") - - time("21:52") - - = 2024-09-16 21:52:00 UTC [DateTime] - - ``` -
- ### `calendar_add` Adds the given time span to a `DateTime`. This uses leap-year and DST-aware calendar arithmetic with variable-length days, months, and years. diff --git a/numbat/modules/datetime/functions.nbt b/numbat/modules/datetime/functions.nbt index 878e96c7..4e350a4d 100644 --- a/numbat/modules/datetime/functions.nbt +++ b/numbat/modules/datetime/functions.nbt @@ -52,7 +52,6 @@ fn date(input: String) -> DateTime = else datetime("{input} 00:00:00") @description("Parses a string (time only) into a `DateTime` object.") -@example("time(\"21:52\")") fn time(input: String) -> DateTime = datetime("{_today_str()} {input}") From 42f29767186de0b34a4a5825cf9868068492a30d Mon Sep 17 00:00:00 2001 From: Bzero Date: Tue, 24 Sep 2024 17:26:15 +0200 Subject: [PATCH 6/9] Apply suggested example formatting --- book/src/list-functions-lists.md | 8 ++++---- book/src/list-functions-math.md | 27 +++++++++++++++++++++------ book/src/list-functions-strings.md | 4 ++-- numbat/modules/core/functions.nbt | 8 ++++---- numbat/modules/core/lists.nbt | 2 +- numbat/modules/core/strings.nbt | 2 +- 6 files changed, 33 insertions(+), 18 deletions(-) diff --git a/book/src/list-functions-lists.md b/book/src/list-functions-lists.md index 7a9659b1..dfad0612 100644 --- a/book/src/list-functions-lists.md +++ b/book/src/list-functions-lists.md @@ -450,14 +450,14 @@ fn linspace(start: D, end: D, n_steps: Scalar) -> List
Examples -* Run this example +* Run this example ```nbt - >>> linspace(0, 10, 11) + >>> linspace(-5 m, 5 m, 11) - linspace(0, 10, 11) + linspace(-(5 metre), 5 metre, 11) - = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10] [List] + = [-5 m, -4 m, -3 m, -2 m, -1 m, 0 m, 1 m, 2 m, 3 m, 4 m, 5 m] [List] ```
diff --git a/book/src/list-functions-math.md b/book/src/list-functions-math.md index 8849b265..e55cdafe 100644 --- a/book/src/list-functions-math.md +++ b/book/src/list-functions-math.md @@ -16,10 +16,10 @@ fn id(x: A) -> A
Examples -* Run this example +* Run this example ```nbt - >>> id(8kg) + >>> id(8 kg) id(8 kilogram) @@ -36,6 +36,21 @@ More information [here](https://doc.rust-lang.org/std/primitive.f64.html#method. fn abs(x: T) -> T ``` +
+Examples + +* Run this example + + ```nbt + >>> abs(-22.2 m) + + abs(-(22.2 metre)) + + = 22.2 m [Length] + + ``` +
+ ### `sqrt` (Square root) Return the square root \\( \sqrt{x} \\) of the input: `sqrt(121 m^2) = 11 m`. More information [here](https://en.wikipedia.org/wiki/Square_root). @@ -47,10 +62,10 @@ fn sqrt(x: D^2) -> D
Examples -* Run this example +* Run this example ```nbt - >>> sqrt(4are) -> m + >>> sqrt(4 are) -> m sqrt(4 are) ➞ metre @@ -70,10 +85,10 @@ fn cbrt(x: D^3) -> D
Examples -* Run this example +* Run this example ```nbt - >>> cbrt(8l) -> cm + >>> cbrt(8 L) -> cm cbrt(8 litre) ➞ centimetre diff --git a/book/src/list-functions-strings.md b/book/src/list-functions-strings.md index b8ca8b78..cb1e1497 100644 --- a/book/src/list-functions-strings.md +++ b/book/src/list-functions-strings.md @@ -144,10 +144,10 @@ fn str_append(a: String, b: String) -> String
Examples -* Run this example +* Run this example ```nbt - >>> str_append("Numbat","!") + >>> str_append("Numbat", "!") str_append("Numbat", "!") diff --git a/numbat/modules/core/functions.nbt b/numbat/modules/core/functions.nbt index a1ee5b76..07c0e757 100644 --- a/numbat/modules/core/functions.nbt +++ b/numbat/modules/core/functions.nbt @@ -2,25 +2,25 @@ use core::scalar @name("Identity function") @description("Return the input value.") -@example("id(8kg)") +@example("id(8 kg)") fn id(x: A) -> A = x @name("Absolute value") @description("Return the absolute value $|x|$ of the input. This works for quantities, too: `abs(-5 m) = 5 m`.") @url("https://doc.rust-lang.org/std/primitive.f64.html#method.abs") -# @example("abs(-22.2m)") +@example("abs(-22.2 m)") fn abs(x: T) -> T @name("Square root") @description("Return the square root $\\sqrt\{x\}$ of the input: `sqrt(121 m^2) = 11 m`.") @url("https://en.wikipedia.org/wiki/Square_root") -@example("sqrt(4are) -> m") +@example("sqrt(4 are) -> m") fn sqrt(x: D^2) -> D = x^(1/2) @name("Cube root") @description("Return the cube root $\\sqrt[3]\{x\}$ of the input: `cbrt(8 m^3) = 2 m`.") @url("https://en.wikipedia.org/wiki/Cube_root") -@example("cbrt(8l) -> cm") +@example("cbrt(8 L) -> cm") fn cbrt(x: D^3) -> D = x^(1/3) @name("Square function") diff --git a/numbat/modules/core/lists.nbt b/numbat/modules/core/lists.nbt index 662383da..ff52b5f7 100644 --- a/numbat/modules/core/lists.nbt +++ b/numbat/modules/core/lists.nbt @@ -139,7 +139,7 @@ fn _linspace_helper(start, end, n_steps, i) = else cons(start + (end - start) * i / (n_steps - 1), _linspace_helper(start, end, n_steps, i + 1)) @description("Generate a list of `n_steps` evenly spaced numbers from `start` to `end` (inclusive)") -@example("linspace(0, 10, 11)") +@example("linspace(-5 m, 5 m, 11)") fn linspace(start: D, end: D, n_steps: Scalar) -> List = if n_steps <= 1 then error("Number of steps must be larger than 1") diff --git a/numbat/modules/core/strings.nbt b/numbat/modules/core/strings.nbt index 609d1cf5..7fd7250f 100644 --- a/numbat/modules/core/strings.nbt +++ b/numbat/modules/core/strings.nbt @@ -27,7 +27,7 @@ fn lowercase(s: String) -> String fn uppercase(s: String) -> String @description("Concatenate two strings") -@example("str_append(\"Numbat\",\"!\")") +@example("str_append(\"Numbat\", \"!\")") fn str_append(a: String, b: String) -> String = "{a}{b}" @description("Find the first occurrence of a substring in a string") From 17c2a9feabdd07cf01d944983541db1b6b974fc8 Mon Sep 17 00:00:00 2001 From: Bzero Date: Tue, 24 Sep 2024 17:38:59 +0200 Subject: [PATCH 7/9] Clone example context instead of re-interpreting --- numbat/examples/inspect.rs | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/numbat/examples/inspect.rs b/numbat/examples/inspect.rs index f1fe019c..c046d057 100644 --- a/numbat/examples/inspect.rs +++ b/numbat/examples/inspect.rs @@ -45,7 +45,7 @@ and — where sensible — units allow for [binary prefixes](https://en.wikipedi } } -fn inspect_functions_in_module(ctx: &Context, module: String) { +fn inspect_functions_in_module(ctx: &Context, prelude_ctx: &Context, module: String) { for (fn_name, name, signature, description, url, examples, code_source) in ctx.functions() { let CodeSource::Module(module_path, _) = code_source else { unreachable!(); @@ -86,11 +86,7 @@ fn inspect_functions_in_module(ctx: &Context, module: String) { println!(); for (example_code, example_description) in examples { - let mut example_ctx = prepare_context(); - let _result = example_ctx - .interpret("use prelude", CodeSource::Internal) - .unwrap(); - + let mut example_ctx = prelude_ctx.clone(); let extra_import = if !example_ctx .resolver() .imported_modules @@ -201,6 +197,11 @@ fn main() { let mut ctx = prepare_context(); let _result = ctx.interpret("use all", CodeSource::Internal).unwrap(); + let mut example_ctx = prepare_context(); + let _result = example_ctx + .interpret("use prelude", CodeSource::Internal) + .unwrap(); + let mut args = std::env::args(); args.next(); if let Some(arg) = args.next() { @@ -208,7 +209,7 @@ fn main() { "units" => inspect_units(&ctx), "functions" => { let module = args.next().unwrap(); - inspect_functions_in_module(&ctx, module) + inspect_functions_in_module(&ctx, &example_ctx, module) } _ => eprintln!("USAGE: inspect [units|functions ]"), } From 45cba264965c79a5622422bed590462c2b263d17 Mon Sep 17 00:00:00 2001 From: Bzero Date: Sun, 29 Sep 2024 14:12:38 +0200 Subject: [PATCH 8/9] Apply example suggestions from code review Co-authored-by: David Peter --- book/src/list-functions-lists.md | 30 ++++++------- book/src/list-functions-math.md | 45 +++++++++++++------ book/src/list-functions-other.md | 24 +++++----- book/src/list-functions-strings.md | 8 ++-- numbat/modules/core/functions.nbt | 2 +- numbat/modules/core/lists.nbt | 6 +-- numbat/modules/core/strings.nbt | 2 +- numbat/modules/math/geometry.nbt | 4 +- numbat/modules/math/number_theory.nbt | 2 +- numbat/modules/numerics/diff.nbt | 3 +- .../physics/temperature_conversion.nbt | 8 ++-- numbat/modules/units/mixed.nbt | 8 ++-- 12 files changed, 78 insertions(+), 64 deletions(-) diff --git a/book/src/list-functions-lists.md b/book/src/list-functions-lists.md index dfad0612..d4416e93 100644 --- a/book/src/list-functions-lists.md +++ b/book/src/list-functions-lists.md @@ -309,18 +309,14 @@ fn filter(p: Fn[(A) -> Bool], xs: List) -> List
Examples -* Filter all elements greater than \\( 1 \\). +* Run this example - Run this example ```nbt - >>> fn filter_fn(x) = x > 1 - filter(filter_fn, [3, 2, 1, 0]) + >>> filter(is_finite, [0, 1e10, NaN, -inf]) - fn filter_fn(x: Scalar) -> Bool = x > 1 + filter(is_finite, [0, 10_000_000_000, NaN, -inf]) - filter(filter_fn, [3, 2, 1, 0]) - - = [3, 2] [List] + = [0, 10_000_000_000] [List] ```
@@ -360,14 +356,14 @@ fn sort_by_key(key: Fn[(A) -> D], xs: List) -> List * Sort by last digit. - Run this example + Run this example ```nbt - >>> fn map_fn(x) = mod(x, 10) - sort_by_key(map_fn, [701, 313, 9999, 4]) + >>> fn last_digit(x) = mod(x, 10) + sort_by_key(last_digit, [701, 313, 9999, 4]) - fn map_fn(x: Scalar) -> Scalar = mod(x, 10) + fn last_digit(x: Scalar) -> Scalar = mod(x, 10) - sort_by_key(map_fn, [701, 313, 9999, 4]) + sort_by_key(last_digit, [701, 313, 9999, 4]) = [701, 313, 4, 9999] [List] @@ -428,14 +424,14 @@ fn sum(xs: List) -> D
Examples -* Run this example +* Run this example ```nbt - >>> sum([3, 2, 1]) + >>> sum([3 m, 200 cm, 1000 mm]) - sum([3, 2, 1]) + sum([3 metre, 200 centimetre, 1000 millimetre]) - = 6 + = 6 m [Length] ```
diff --git a/book/src/list-functions-math.md b/book/src/list-functions-math.md index e55cdafe..6b224d44 100644 --- a/book/src/list-functions-math.md +++ b/book/src/list-functions-math.md @@ -267,7 +267,7 @@ fn ceil(x: Scalar) -> Scalar
### `ceil_in` (Ceil function) -Returns the smallest integer multuple of `base` greater than or equal to `value`. +Returns the smallest integer multiple of `base` greater than or equal to `value`. ```nbt fn ceil_in(base: D, value: D) -> D @@ -859,10 +859,10 @@ fn gcd(a: Scalar, b: Scalar) -> Scalar
Examples -* Run this example +* Run this example ```nbt - >>> gcd(60,42) + >>> gcd(60, 42) gcd(60, 42) @@ -909,11 +909,11 @@ fn diff(f: Fn[(X) -> Y], x: X) -> Y / X
Examples -* Compute the drivative of \\( f(x) = x² -x -1 \\) at \\( x=1 \\). +* Compute the derivative of \\( f(x) = x² -x -1 \\) at \\( x=1 \\). - Run this example + Run this example ```nbt - >>> fn polynomial(x) = x² -x -1 + >>> fn polynomial(x) = x² - x - 1 diff(polynomial, 1) fn polynomial(x: Scalar) -> Scalar = (x² - x) - 1 @@ -922,6 +922,23 @@ fn diff(f: Fn[(X) -> Y], x: X) -> Y / X = 1.0 + ``` +* Compute the free fall velocity after \\( t=2 s \\). + + Run this example + ```nbt + >>> fn distance(t) = 0.5 g0 t² + fn velocity(t) = diff(distance, t) + velocity(2 s) + + fn distance(t: A) -> A² × Length / Time² = 0.5 g0 × t² + + fn velocity(t: A) -> A × Length / Time² = diff(distance, t) + + velocity(2 second) + + = 19.6133 m/s [Velocity] + ```
@@ -1023,14 +1040,14 @@ fn hypot2(x: T, y: T) -> T
Examples -* Run this example +* Run this example ```nbt - >>> hypot2(3, 4) + >>> hypot2(3 m, 4 m) - hypot2(3, 4) + hypot2(3 metre, 4 metre) - = 5 + = 5 m [Length] ```
@@ -1045,14 +1062,14 @@ fn hypot3(x: T, y: T, z: T) -> T
Examples -* Run this example +* Run this example ```nbt - >>> hypot3(4, 1, 4) + >>> hypot3(8, 9, 12) - hypot3(4, 1, 4) + hypot3(8, 9, 12) - = 5.74456 + = 17 ```
diff --git a/book/src/list-functions-other.md b/book/src/list-functions-other.md index ef5173d1..804d93c4 100644 --- a/book/src/list-functions-other.md +++ b/book/src/list-functions-other.md @@ -216,10 +216,10 @@ fn DMS(alpha: Angle) -> String
Examples -* Run this example +* Run this example ```nbt - >>> DMS(46.5858°) + >>> 46.5858° -> DMS DMS(46.5858 degree) @@ -239,10 +239,10 @@ fn DM(alpha: Angle) -> String
Examples -* Run this example +* Run this example ```nbt - >>> DM(46.5858°) + >>> 46.5858° -> DM DM(46.5858 degree) @@ -262,10 +262,10 @@ fn feet_and_inches(length: Length) -> String
Examples -* Run this example +* Run this example ```nbt - >>> feet_and_inches(180cm) + >>> 180 cm -> feet_and_inches feet_and_inches(180 centimetre) @@ -285,10 +285,10 @@ fn pounds_and_ounces(mass: Mass) -> String
Examples -* Run this example +* Run this example ```nbt - >>> pounds_and_ounces(1kg) + >>> 1 kg -> pounds_and_ounces pounds_and_ounces(1 kilogram) @@ -312,7 +312,7 @@ fn from_celsius(t_celsius: Scalar) -> Temperature
Examples -* \\( 300 °C \\) in Kelvin. +* 300 °C in Kelvin. Run this example ```nbt @@ -336,7 +336,7 @@ fn celsius(t_kelvin: Temperature) -> Scalar
Examples -* \\( 300K \\) in degree Celsius. +* 300 K in degree Celsius. Run this example ```nbt @@ -360,7 +360,7 @@ fn from_fahrenheit(t_fahrenheit: Scalar) -> Temperature
Examples -* \\( 300 °F \\) in Kelvin. +* 300 °F in Kelvin. Run this example ```nbt @@ -384,7 +384,7 @@ fn fahrenheit(t_kelvin: Temperature) -> Scalar
Examples -* \\( 300K \\) in degree Fahrenheit. +* 300 K in degree Fahrenheit. Run this example ```nbt diff --git a/book/src/list-functions-strings.md b/book/src/list-functions-strings.md index cb1e1497..59df2308 100644 --- a/book/src/list-functions-strings.md +++ b/book/src/list-functions-strings.md @@ -34,14 +34,14 @@ fn str_slice(s: String, start: Scalar, end: Scalar) -> String
Examples -* Run this example +* Run this example ```nbt - >>> str_slice("Numbat", 0, 2) + >>> str_slice("Numbat", 3, 6) - str_slice("Numbat", 0, 2) + str_slice("Numbat", 3, 6) - = "Nu" [String] + = "bat" [String] ```
diff --git a/numbat/modules/core/functions.nbt b/numbat/modules/core/functions.nbt index 07c0e757..75d36b52 100644 --- a/numbat/modules/core/functions.nbt +++ b/numbat/modules/core/functions.nbt @@ -60,7 +60,7 @@ fn floor_in(base: D, value: D) -> D = floor(value / base) × base fn ceil(x: Scalar) -> Scalar @name("Ceil function") -@description("Returns the smallest integer multuple of `base` greater than or equal to `value`.") +@description("Returns the smallest integer multiple of `base` greater than or equal to `value`.") @example("ceil_in(m, 5.3 m)", "Ceil in meters.") @example("ceil_in(cm, 5.3 m)", "Ceil in centimeters.") diff --git a/numbat/modules/core/lists.nbt b/numbat/modules/core/lists.nbt index ff52b5f7..8c56dc49 100644 --- a/numbat/modules/core/lists.nbt +++ b/numbat/modules/core/lists.nbt @@ -78,7 +78,7 @@ fn map(f: Fn[(A) -> B], xs: List) -> List = else cons(f(head(xs)), map(f, tail(xs))) @description("Filter a list by a predicate") -@example("fn filter_fn(x) = x > 1\nfilter(filter_fn, [3, 2, 1, 0])", "Filter all elements greater than $1$.") +@example("filter(is_finite, [0, 1e10, NaN, -inf])") fn filter(p: Fn[(A) -> Bool], xs: List) -> List = if is_empty(xs) then [] @@ -104,7 +104,7 @@ fn _merge(xs, ys, cmp) = @description("Sort a list of elements, using the given key function that maps the element to a quantity") -@example("fn map_fn(x) = mod(x, 10)\nsort_by_key(map_fn, [701, 313, 9999, 4])","Sort by last digit.") +@example("fn last_digit(x) = mod(x, 10)\nsort_by_key(last_digit, [701, 313, 9999, 4])","Sort by last digit.") fn sort_by_key(key: Fn[(A) -> D], xs: List) -> List = if is_empty(xs) then [] @@ -129,7 +129,7 @@ fn intersperse(sep: A, xs: List) -> List = fn _add(x, y) = x + y # TODO: replace this with a local function once we support them @description("Sum all elements of a list") -@example("sum([3, 2, 1])") +@example("sum([3 m, 200 cm, 1000 mm])") fn sum(xs: List) -> D = foldl(_add, 0, xs) # TODO: implement linspace using `map` or similar once we have closures. This is ugly. diff --git a/numbat/modules/core/strings.nbt b/numbat/modules/core/strings.nbt index 7fd7250f..aa21dab5 100644 --- a/numbat/modules/core/strings.nbt +++ b/numbat/modules/core/strings.nbt @@ -7,7 +7,7 @@ use core::error fn str_length(s: String) -> Scalar @description("Subslice of a string") -@example("str_slice(\"Numbat\", 0, 2)") +@example("str_slice(\"Numbat\", 3, 6)") fn str_slice(s: String, start: Scalar, end: Scalar) -> String @description("Get a single-character string from a Unicode code point.") diff --git a/numbat/modules/math/geometry.nbt b/numbat/modules/math/geometry.nbt index 57b09932..942ca671 100644 --- a/numbat/modules/math/geometry.nbt +++ b/numbat/modules/math/geometry.nbt @@ -2,11 +2,11 @@ use core::functions use math::constants @description("The length of the hypotenuse of a right-angled triangle $\\sqrt\{x^2+y^2\}$.") -@example("hypot2(3, 4)") +@example("hypot2(3 m, 4 m)") fn hypot2(x: T, y: T) -> T = sqrt(x^2 + y^2) @description("The Euclidean norm of a 3D vector $\\sqrt\{x^2+y^2+z^2\}$.") -@example("hypot3(4, 1, 4)") +@example("hypot3(8, 9, 12)") fn hypot3(x: T, y: T, z: T) -> T = sqrt(x^2 + y^2 + z^2) # The following functions use a generic dimension instead of diff --git a/numbat/modules/math/number_theory.nbt b/numbat/modules/math/number_theory.nbt index 1bef78c7..a9a4a917 100644 --- a/numbat/modules/math/number_theory.nbt +++ b/numbat/modules/math/number_theory.nbt @@ -4,7 +4,7 @@ use core::functions @name("Greatest common divisor") @description("The largest positive integer that divides each of the integers $a$ and $b$.") @url("https://en.wikipedia.org/wiki/Greatest_common_divisor") -@example("gcd(60,42)") +@example("gcd(60, 42)") fn gcd(a: Scalar, b: Scalar) -> Scalar = if b == 0 then abs(a) diff --git a/numbat/modules/numerics/diff.nbt b/numbat/modules/numerics/diff.nbt index e96ca391..820555e2 100644 --- a/numbat/modules/numerics/diff.nbt +++ b/numbat/modules/numerics/diff.nbt @@ -3,7 +3,8 @@ use core::quantities @name("Numerical differentiation") @url("https://en.wikipedia.org/wiki/Numerical_differentiation") @description("Compute the numerical derivative of the function $f$ at point $x$ using the central difference method.") -@example("fn polynomial(x) = x² -x -1\ndiff(polynomial, 1)", "Compute the drivative of $f(x) = x² -x -1$ at $x=1$.") +@example("fn polynomial(x) = x² - x - 1\ndiff(polynomial, 1)", "Compute the derivative of $f(x) = x² -x -1$ at $x=1$.") +@example("fn distance(t) = 0.5 g0 t²\nfn velocity(t) = diff(distance, t)\nvelocity(2 s)", "Compute the free fall velocity after $t=2 s$.") fn diff(f: Fn[(X) -> Y], x: X) -> Y / X = (f(x + Δx) - f(x - Δx)) / 2 Δx where diff --git a/numbat/modules/physics/temperature_conversion.nbt b/numbat/modules/physics/temperature_conversion.nbt index 89a2bc16..8a5ec884 100644 --- a/numbat/modules/physics/temperature_conversion.nbt +++ b/numbat/modules/physics/temperature_conversion.nbt @@ -5,12 +5,12 @@ use units::si let _offset_celsius = 273.15 @description("Converts from degree Celsius (°C) to Kelvin.") -@example("from_celsius(300)", "$300 °C$ in Kelvin.") +@example("from_celsius(300)", "300 °C in Kelvin.") @url("https://en.wikipedia.org/wiki/Conversion_of_scales_of_temperature") fn from_celsius(t_celsius: Scalar) -> Temperature = (t_celsius + _offset_celsius) kelvin @description("Converts from Kelvin to degree Celcius (°C). This can be used on the right hand side of a conversion operator: `200 K -> celsius`.") -@example("300K -> celsius", "$300K$ in degree Celsius.") +@example("300K -> celsius", "300 K in degree Celsius.") @url("https://en.wikipedia.org/wiki/Conversion_of_scales_of_temperature") fn celsius(t_kelvin: Temperature) -> Scalar = t_kelvin / kelvin - _offset_celsius @@ -18,11 +18,11 @@ let _offset_fahrenheit = 459.67 let _scale_fahrenheit = 5 / 9 @description("Converts from degree Fahrenheit (°F) to Kelvin.") -@example("from_fahrenheit(300)", "$300 °F$ in Kelvin.") +@example("from_fahrenheit(300)", "300 °F in Kelvin.") @url("https://en.wikipedia.org/wiki/Conversion_of_scales_of_temperature") fn from_fahrenheit(t_fahrenheit: Scalar) -> Temperature = ((t_fahrenheit + _offset_fahrenheit) × _scale_fahrenheit) kelvin @description("Converts from Kelvin to degree Fahrenheit (°F). This can be used on the right hand side of a conversion operator: `200 K -> fahrenheit`.") -@example("300K -> fahrenheit", "$300K$ in degree Fahrenheit.") +@example("300K -> fahrenheit", "300 K in degree Fahrenheit.") @url("https://en.wikipedia.org/wiki/Conversion_of_scales_of_temperature") fn fahrenheit(t_kelvin: Temperature) -> Scalar = (t_kelvin / kelvin) / _scale_fahrenheit - _offset_fahrenheit diff --git a/numbat/modules/units/mixed.nbt b/numbat/modules/units/mixed.nbt index 9b688cf3..ba9515d0 100644 --- a/numbat/modules/units/mixed.nbt +++ b/numbat/modules/units/mixed.nbt @@ -5,13 +5,13 @@ use units::imperial @name("Degrees, minutes, seconds") @description("Convert an angle to a mixed degrees, (arc)minutes, and (arc)seconds representation. Also called sexagesimal degree notation.") @url("https://en.wikipedia.org/wiki/Sexagesimal_degree") -@example("DMS(46.5858°)") +@example("46.5858° -> DMS") fn DMS(alpha: Angle) -> String = _mixed_units(alpha, [deg, arcmin, arcsec], ["° ", "′ ", "″"], true) @name("Degrees, decimal minutes") @description("Convert an angle to a mixed degrees and decimal minutes representation.") -@example("DM(46.5858°)") +@example("46.5858° -> DM") @url("https://en.wikipedia.org/wiki/Decimal_degrees") fn DM(alpha: Angle) -> String = _mixed_units(alpha, [deg, arcmin], ["° ", "′"], false) @@ -19,13 +19,13 @@ fn DM(alpha: Angle) -> String = @name("Feet and inches") @description("Convert a length to a mixed feet and inches representation.") @url("https://en.wikipedia.org/wiki/Foot_(unit)") -@example("feet_and_inches(180cm)") +@example("180 cm -> feet_and_inches") fn feet_and_inches(length: Length) -> String = _mixed_units(length, [foot, inch], [" ft ", " in"], false) @name("Pounds and ounces") @description("Convert a mass to a mixed pounds and ounces representation.") @url("https://en.wikipedia.org/wiki/Pound_(mass)") -@example("pounds_and_ounces(1kg)") +@example("1 kg -> pounds_and_ounces") fn pounds_and_ounces(mass: Mass) -> String = _mixed_units(mass, [pound, ounce], [" lb ", " oz"], false) From 024f2d3c0a8421cb267939852d7df87efa59dfb0 Mon Sep 17 00:00:00 2001 From: Bzero Date: Fri, 4 Oct 2024 20:52:04 +0200 Subject: [PATCH 9/9] More compact examples --- book/src/list-functions-datetime.md | 209 +++------- book/src/list-functions-lists.md | 321 +++++--------- book/src/list-functions-math.md | 627 +++++++++------------------- book/src/list-functions-other.md | 335 +++++---------- book/src/list-functions-strings.md | 210 +++------- numbat/examples/inspect.rs | 43 +- 6 files changed, 563 insertions(+), 1182 deletions(-) diff --git a/book/src/list-functions-datetime.md b/book/src/list-functions-datetime.md index ebedccc8..8319a503 100644 --- a/book/src/list-functions-datetime.md +++ b/book/src/list-functions-datetime.md @@ -21,36 +21,21 @@ fn datetime(input: String) -> DateTime
Examples -* Run this example - - ```nbt - >>> datetime("2022-07-20T21:52+0200") - - datetime("2022-07-20T21:52+0200") - - = 2022-07-20 19:52:00 UTC [DateTime] - - ``` -* Run this example - - ```nbt - >>> datetime("2022-07-20 21:52 Europe/Berlin") - - datetime("2022-07-20 21:52 Europe/Berlin") - - = 2022-07-20 21:52:00 CEST (UTC +02), Europe/Berlin [DateTime] - - ``` -* Run this example - - ```nbt - >>> datetime("2022/07/20 09:52 PM +0200") - - datetime("2022/07/20 09:52 PM +0200") - - = 2022-07-20 21:52:00 (UTC +02) [DateTime] - - ``` +
>>> datetime("2022-07-20T21:52+0200")
+
+    = 2022-07-20 19:52:00 UTC    [DateTime]
+
+ +
>>> datetime("2022-07-20 21:52 Europe/Berlin")
+
+    = 2022-07-20 21:52:00 CEST (UTC +02), Europe/Berlin    [DateTime]
+
+ +
>>> datetime("2022/07/20 09:52 PM +0200")
+
+    = 2022-07-20 21:52:00 (UTC +02)    [DateTime]
+
+
### `format_datetime` @@ -63,16 +48,11 @@ fn format_datetime(format: String, input: DateTime) -> String
Examples -* Run this example +
>>> format_datetime("This is a date in %B in the year %Y.", datetime("2022-07-20 21:52 +0200"))
+
+    = "This is a date in July in the year 2022."    [String]
+
- ```nbt - >>> format_datetime("This is a date in %B in the year %Y.", datetime("2022-07-20 21:52 +0200")) - - format_datetime("This is a date in %B in the year %Y.", datetime("2022-07-20 21:52 +0200")) - - = "This is a date in July in the year 2022." [String] - - ```
### `get_local_timezone` @@ -85,16 +65,11 @@ fn get_local_timezone() -> String
Examples -* Run this example +
>>> get_local_timezone()
+
+    = "UTC"    [String]
+
- ```nbt - >>> get_local_timezone() - - get_local_timezone() - - = "UTC" [String] - - ```
### `tz` @@ -107,26 +82,16 @@ fn tz(tz: String) -> Fn[(DateTime) -> DateTime]
Examples -* Run this example - - ```nbt - >>> datetime("2022-07-20 21:52 +0200") -> tz("Europe/Amsterdam") - - tz("Europe/Amsterdam")(datetime("2022-07-20 21:52 +0200")) - - = 2022-07-20 21:52:00 CEST (UTC +02), Europe/Amsterdam [DateTime] - - ``` -* Run this example - - ```nbt - >>> datetime("2022-07-20 21:52 +0200") -> tz("Asia/Taipei") - - tz("Asia/Taipei")(datetime("2022-07-20 21:52 +0200")) - - = 2022-07-21 03:52:00 CST (UTC +08), Asia/Taipei [DateTime] - - ``` +
>>> datetime("2022-07-20 21:52 +0200") -> tz("Europe/Amsterdam")
+
+    = 2022-07-20 21:52:00 CEST (UTC +02), Europe/Amsterdam    [DateTime]
+
+ +
>>> datetime("2022-07-20 21:52 +0200") -> tz("Asia/Taipei")
+
+    = 2022-07-21 03:52:00 CST (UTC +08), Asia/Taipei    [DateTime]
+
+
### `unixtime` @@ -139,16 +104,11 @@ fn unixtime(input: DateTime) -> Scalar
Examples -* Run this example +
>>> datetime("2022-07-20 21:52 +0200") -> unixtime
+
+    = 1_658_346_720
+
- ```nbt - >>> datetime("2022-07-20 21:52 +0200") -> unixtime - - unixtime(datetime("2022-07-20 21:52 +0200")) - - = 1_658_346_720 - - ```
### `from_unixtime` @@ -161,16 +121,11 @@ fn from_unixtime(input: Scalar) -> DateTime
Examples -* Run this example +
>>> from_unixtime(2^31)
+
+    = 2038-01-19 03:14:08 UTC    [DateTime]
+
- ```nbt - >>> from_unixtime(2^31) - - from_unixtime(2^31) - - = 2038-01-19 03:14:08 UTC [DateTime] - - ```
### `today` @@ -190,16 +145,11 @@ fn date(input: String) -> DateTime
Examples -* Run this example +
>>> date("2022-07-20")
+
+    = 2022-07-20 00:00:00 UTC    [DateTime]
+
- ```nbt - >>> date("2022-07-20") - - date("2022-07-20") - - = 2022-07-20 00:00:00 UTC [DateTime] - - ```
### `time` @@ -219,16 +169,11 @@ fn calendar_add(dt: DateTime, span: Time) -> DateTime
Examples -* Run this example +
>>> calendar_add(datetime("2022-07-20 21:52 +0200"), 2 years)
+
+    = 2024-07-20 21:52:00 (UTC +02)    [DateTime]
+
- ```nbt - >>> calendar_add(datetime("2022-07-20 21:52 +0200"), 2 years) - - calendar_add(datetime("2022-07-20 21:52 +0200"), 2 year) - - = 2024-07-20 21:52:00 (UTC +02) [DateTime] - - ```
### `calendar_sub` @@ -241,16 +186,11 @@ fn calendar_sub(dt: DateTime, span: Time) -> DateTime
Examples -* Run this example +
>>> calendar_sub(datetime("2022-07-20 21:52 +0200"), 3 years)
+
+    = 2019-07-20 21:52:00 (UTC +02)    [DateTime]
+
- ```nbt - >>> calendar_sub(datetime("2022-07-20 21:52 +0200"), 3 years) - - calendar_sub(datetime("2022-07-20 21:52 +0200"), 3 year) - - = 2019-07-20 21:52:00 (UTC +02) [DateTime] - - ```
### `weekday` @@ -263,16 +203,11 @@ fn weekday(dt: DateTime) -> String
Examples -* Run this example +
>>> weekday(datetime("2022-07-20 21:52 +0200"))
+
+    = "Wednesday"    [String]
+
- ```nbt - >>> weekday(datetime("2022-07-20 21:52 +0200")) - - weekday(datetime("2022-07-20 21:52 +0200")) - - = "Wednesday" [String] - - ```
### `julian_date` (Julian date) @@ -286,16 +221,11 @@ fn julian_date(dt: DateTime) -> Time
Examples -* Run this example +
>>> julian_date(datetime("2022-07-20 21:52 +0200"))
+
+    = 2.45978e+6 day    [Time]
+
- ```nbt - >>> julian_date(datetime("2022-07-20 21:52 +0200")) - - julian_date(datetime("2022-07-20 21:52 +0200")) - - = 2.45978e+6 day [Time] - - ```
### `human` (Human-readable time duration) @@ -309,16 +239,11 @@ fn human(time: Time) -> String
Examples -* How long is a microcentury? - - Run this example - ```nbt - >>> century/1e6 -> human - - human(century / 1_000_000) - - = "52 minutes + 35.692505184 seconds" [String] - - ``` +How long is a microcentury? +
>>> century/1e6 -> human
+
+    = "52 minutes + 35.692505184 seconds"    [String]
+
+
diff --git a/book/src/list-functions-lists.md b/book/src/list-functions-lists.md index d4416e93..c3919ea0 100644 --- a/book/src/list-functions-lists.md +++ b/book/src/list-functions-lists.md @@ -12,16 +12,11 @@ fn len(xs: List) -> Scalar
Examples -* Run this example - - ```nbt - >>> len([3, 2, 1]) - - len([3, 2, 1]) - - = 3 - - ``` +
>>> len([3, 2, 1])
+
+    = 3
+
+
### `head` @@ -34,16 +29,11 @@ fn head(xs: List) -> A
Examples -* Run this example +
>>> head([3, 2, 1])
+
+    = 3
+
- ```nbt - >>> head([3, 2, 1]) - - head([3, 2, 1]) - - = 3 - - ```
### `tail` @@ -56,16 +46,11 @@ fn tail(xs: List) -> List
Examples -* Run this example +
>>> tail([3, 2, 1])
+
+    = [2, 1]    [List]
+
- ```nbt - >>> tail([3, 2, 1]) - - tail([3, 2, 1]) - - = [2, 1] [List] - - ```
### `cons` @@ -78,16 +63,11 @@ fn cons(x: A, xs: List) -> List
Examples -* Run this example +
>>> cons(77, [3, 2, 1])
+
+    = [77, 3, 2, 1]    [List]
+
- ```nbt - >>> cons(77, [3, 2, 1]) - - cons(77, [3, 2, 1]) - - = [77, 3, 2, 1] [List] - - ```
### `cons_end` @@ -100,16 +80,11 @@ fn cons_end(x: A, xs: List) -> List
Examples -* Run this example +
>>> cons_end(77, [3, 2, 1])
+
+    = [3, 2, 1, 77]    [List]
+
- ```nbt - >>> cons_end(77, [3, 2, 1]) - - cons_end(77, [3, 2, 1]) - - = [3, 2, 1, 77] [List] - - ```
### `is_empty` @@ -122,26 +97,16 @@ fn is_empty(xs: List) -> Bool
Examples -* Run this example - - ```nbt - >>> is_empty([3, 2, 1]) - - is_empty([3, 2, 1]) - - = false [Bool] - - ``` -* Run this example - - ```nbt - >>> is_empty([]) - - is_empty([]) - - = true [Bool] - - ``` +
>>> is_empty([3, 2, 1])
+
+    = false    [Bool]
+
+ +
>>> is_empty([])
+
+    = true    [Bool]
+
+
### `concat` @@ -154,16 +119,11 @@ fn concat(xs1: List, xs2: List) -> List
Examples -* Run this example +
>>> concat([3, 2, 1], [10, 11])
+
+    = [3, 2, 1, 10, 11]    [List]
+
- ```nbt - >>> concat([3, 2, 1], [10, 11]) - - concat([3, 2, 1], [10, 11]) - - = [3, 2, 1, 10, 11] [List] - - ```
### `take` @@ -176,16 +136,11 @@ fn take(n: Scalar, xs: List) -> List
Examples -* Run this example +
>>> take(2, [3, 2, 1, 0])
+
+    = [3, 2]    [List]
+
- ```nbt - >>> take(2, [3, 2, 1, 0]) - - take(2, [3, 2, 1, 0]) - - = [3, 2] [List] - - ```
### `drop` @@ -198,16 +153,11 @@ fn drop(n: Scalar, xs: List) -> List
Examples -* Run this example +
>>> drop(2, [3, 2, 1, 0])
+
+    = [1, 0]    [List]
+
- ```nbt - >>> drop(2, [3, 2, 1, 0]) - - drop(2, [3, 2, 1, 0]) - - = [1, 0] [List] - - ```
### `element_at` @@ -220,16 +170,11 @@ fn element_at(i: Scalar, xs: List) -> A
Examples -* Run this example +
>>> element_at(2, [3, 2, 1, 0])
+
+    = 1
+
- ```nbt - >>> element_at(2, [3, 2, 1, 0]) - - element_at(2, [3, 2, 1, 0]) - - = 1 - - ```
### `range` @@ -242,16 +187,11 @@ fn range(start: Scalar, end: Scalar) -> List
Examples -* Run this example +
>>> range(2, 12)
+
+    = [2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]    [List]
+
- ```nbt - >>> range(2, 12) - - range(2, 12) - - = [2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] [List] - - ```
### `reverse` @@ -264,16 +204,11 @@ fn reverse(xs: List) -> List
Examples -* Run this example +
>>> reverse([3, 2, 1])
+
+    = [1, 2, 3]    [List]
+
- ```nbt - >>> reverse([3, 2, 1]) - - reverse([3, 2, 1]) - - = [1, 2, 3] [List] - - ```
### `map` @@ -286,17 +221,12 @@ fn map(f: Fn[(A) -> B], xs: List) -> List
Examples -* Square all elements of a list. - - Run this example - ```nbt - >>> map(sqr, [3, 2, 1]) - - map(sqr, [3, 2, 1]) - - = [9, 4, 1] [List] - - ``` +Square all elements of a list. +
>>> map(sqr, [3, 2, 1])
+
+    = [9, 4, 1]    [List]
+
+
### `filter` @@ -309,16 +239,11 @@ fn filter(p: Fn[(A) -> Bool], xs: List) -> List
Examples -* Run this example +
>>> filter(is_finite, [0, 1e10, NaN, -inf])
+
+    = [0, 10_000_000_000]    [List]
+
- ```nbt - >>> filter(is_finite, [0, 1e10, NaN, -inf]) - - filter(is_finite, [0, 10_000_000_000, NaN, -inf]) - - = [0, 10_000_000_000] [List] - - ```
### `foldl` @@ -331,17 +256,12 @@ fn foldl(f: Fn[(A, B) -> A], acc: A, xs: List) -> A
Examples -* Join a list of strings by folding. - - Run this example - ```nbt - >>> foldl(str_append, "", ["Num", "bat", "!"]) - - foldl(str_append, "", ["Num", "bat", "!"]) - - = "Numbat!" [String] - - ``` +Join a list of strings by folding. +
>>> foldl(str_append, "", ["Num", "bat", "!"])
+
+    = "Numbat!"    [String]
+
+
### `sort_by_key` @@ -354,20 +274,13 @@ fn sort_by_key(key: Fn[(A) -> D], xs: List) -> List
Examples -* Sort by last digit. - - Run this example - ```nbt - >>> fn last_digit(x) = mod(x, 10) - sort_by_key(last_digit, [701, 313, 9999, 4]) - - fn last_digit(x: Scalar) -> Scalar = mod(x, 10) - - sort_by_key(last_digit, [701, 313, 9999, 4]) - - = [701, 313, 4, 9999] [List] - - ``` +Sort by last digit. +
>>> fn last_digit(x) = mod(x, 10)
+sort_by_key(last_digit, [701, 313, 9999, 4])
+
+    = [701, 313, 4, 9999]    [List]
+
+
### `sort` @@ -380,16 +293,11 @@ fn sort(xs: List) -> List
Examples -* Run this example +
>>> sort([3, 2, 7, 8, -4, 0, -5])
+
+    = [-5, -4, 0, 2, 3, 7, 8]    [List]
+
- ```nbt - >>> sort([3, 2, 7, 8, -4, 0, -5]) - - sort([3, 2, 7, 8, -4, 0, -5]) - - = [-5, -4, 0, 2, 3, 7, 8] [List] - - ```
### `intersperse` @@ -402,16 +310,11 @@ fn intersperse(sep: A, xs: List) -> List
Examples -* Run this example +
>>> intersperse(0, [1, 1, 1, 1])
+
+    = [1, 0, 1, 0, 1, 0, 1]    [List]
+
- ```nbt - >>> intersperse(0, [1, 1, 1, 1]) - - intersperse(0, [1, 1, 1, 1]) - - = [1, 0, 1, 0, 1, 0, 1] [List] - - ```
### `sum` @@ -424,16 +327,11 @@ fn sum(xs: List) -> D
Examples -* Run this example +
>>> sum([3 m, 200 cm, 1000 mm])
+
+    = 6 m    [Length]
+
- ```nbt - >>> sum([3 m, 200 cm, 1000 mm]) - - sum([3 metre, 200 centimetre, 1000 millimetre]) - - = 6 m [Length] - - ```
### `linspace` @@ -446,16 +344,11 @@ fn linspace(start: D, end: D, n_steps: Scalar) -> List
Examples -* Run this example +
>>> linspace(-5 m, 5 m, 11)
+
+    = [-5 m, -4 m, -3 m, -2 m, -1 m, 0 m, 1 m, 2 m, 3 m, 4 m, 5 m]    [List]
+
- ```nbt - >>> linspace(-5 m, 5 m, 11) - - linspace(-(5 metre), 5 metre, 11) - - = [-5 m, -4 m, -3 m, -2 m, -1 m, 0 m, 1 m, 2 m, 3 m, 4 m, 5 m] [List] - - ```
### `join` @@ -468,16 +361,11 @@ fn join(xs: List, sep: String) -> String
Examples -* Run this example +
>>> join(["snake", "case"], "_")
+
+    = "snake_case"    [String]
+
- ```nbt - >>> join(["snake", "case"], "_") - - join(["snake", "case"], "_") - - = "snake_case" [String] - - ```
### `split` @@ -490,15 +378,10 @@ fn split(input: String, separator: String) -> List
Examples -* Run this example +
>>> split("Numbat is a statically typed programming language.", " ")
+
+    = ["Numbat", "is", "a", "statically", "typed", "programming", "language."]    [List]
+
- ```nbt - >>> split("Numbat is a statically typed programming language.", " ") - - split("Numbat is a statically typed programming language.", " ") - - = ["Numbat", "is", "a", "statically", "typed", "programming", "language."] [List] - - ```
diff --git a/book/src/list-functions-math.md b/book/src/list-functions-math.md index 6b224d44..62464657 100644 --- a/book/src/list-functions-math.md +++ b/book/src/list-functions-math.md @@ -16,16 +16,11 @@ fn id(x: A) -> A
Examples -* Run this example - - ```nbt - >>> id(8 kg) - - id(8 kilogram) - - = 8 kg [Mass] - - ``` +
>>> id(8 kg)
+
+    = 8 kg    [Mass]
+
+
### `abs` (Absolute value) @@ -39,16 +34,11 @@ fn abs(x: T) -> T
Examples -* Run this example +
>>> abs(-22.2 m)
+
+    = 22.2 m    [Length]
+
- ```nbt - >>> abs(-22.2 m) - - abs(-(22.2 metre)) - - = 22.2 m [Length] - - ```
### `sqrt` (Square root) @@ -62,16 +52,11 @@ fn sqrt(x: D^2) -> D
Examples -* Run this example +
>>> sqrt(4 are) -> m
+
+    = 20 m    [Length]
+
- ```nbt - >>> sqrt(4 are) -> m - - sqrt(4 are) ➞ metre - - = 20 m [Length] - - ```
### `cbrt` (Cube root) @@ -85,16 +70,11 @@ fn cbrt(x: D^3) -> D
Examples -* Run this example +
>>> cbrt(8 L) -> cm
+
+    = 20.0 cm    [Length]
+
- ```nbt - >>> cbrt(8 L) -> cm - - cbrt(8 litre) ➞ centimetre - - = 20.0 cm [Length] - - ```
### `sqr` (Square function) @@ -107,16 +87,11 @@ fn sqr(x: D) -> D^2
Examples -* Run this example +
>>> sqr(7)
+
+    = 49
+
- ```nbt - >>> sqr(7) - - sqr(7) - - = 49 - - ```
### `round` (Rounding) @@ -130,26 +105,16 @@ fn round(x: Scalar) -> Scalar
Examples -* Run this example - - ```nbt - >>> round(5.5) - - round(5.5) - - = 6 - - ``` -* Run this example - - ```nbt - >>> round(-5.5) - - round(-5.5) - - = -6 - - ``` +
>>> round(5.5)
+
+    = 6
+
+ +
>>> round(-5.5)
+
+    = -6
+
+
### `round_in` (Rounding) @@ -162,28 +127,18 @@ fn round_in(base: D, value: D) -> D
Examples -* Round in meters. - - Run this example - ```nbt - >>> round_in(m, 5.3 m) - - round_in(metre, 5.3 metre) - - = 5 m [Length] - - ``` -* Round in centimeters. - - Run this example - ```nbt - >>> round_in(cm, 5.3 m) - - round_in(centimetre, 5.3 metre) - - = 530 cm [Length] - - ``` +Round in meters. +
>>> round_in(m, 5.3 m)
+
+    = 5 m    [Length]
+
+ +Round in centimeters. +
>>> round_in(cm, 5.3 m)
+
+    = 530 cm    [Length]
+
+
### `floor` (Floor function) @@ -197,16 +152,11 @@ fn floor(x: Scalar) -> Scalar
Examples -* Run this example +
>>> floor(5.5)
+
+    = 5
+
- ```nbt - >>> floor(5.5) - - floor(5.5) - - = 5 - - ```
### `floor_in` (Floor function) @@ -219,28 +169,18 @@ fn floor_in(base: D, value: D) -> D
Examples -* Floor in meters. - - Run this example - ```nbt - >>> floor_in(m, 5.7 m) - - floor_in(metre, 5.7 metre) - - = 5 m [Length] - - ``` -* Floor in centimeters. - - Run this example - ```nbt - >>> floor_in(cm, 5.7 m) - - floor_in(centimetre, 5.7 metre) - - = 570 cm [Length] - - ``` +Floor in meters. +
>>> floor_in(m, 5.7 m)
+
+    = 5 m    [Length]
+
+ +Floor in centimeters. +
>>> floor_in(cm, 5.7 m)
+
+    = 570 cm    [Length]
+
+
### `ceil` (Ceil function) @@ -254,16 +194,11 @@ fn ceil(x: Scalar) -> Scalar
Examples -* Run this example +
>>> ceil(5.5)
+
+    = 6
+
- ```nbt - >>> ceil(5.5) - - ceil(5.5) - - = 6 - - ```
### `ceil_in` (Ceil function) @@ -276,28 +211,18 @@ fn ceil_in(base: D, value: D) -> D
Examples -* Ceil in meters. - - Run this example - ```nbt - >>> ceil_in(m, 5.3 m) - - ceil_in(metre, 5.3 metre) - - = 6 m [Length] - - ``` -* Ceil in centimeters. - - Run this example - ```nbt - >>> ceil_in(cm, 5.3 m) - - ceil_in(centimetre, 5.3 metre) - - = 530 cm [Length] - - ``` +Ceil in meters. +
>>> ceil_in(m, 5.3 m)
+
+    = 6 m    [Length]
+
+ +Ceil in centimeters. +
>>> ceil_in(cm, 5.3 m)
+
+    = 530 cm    [Length]
+
+
### `trunc` (Truncation) @@ -311,26 +236,16 @@ fn trunc(x: Scalar) -> Scalar
Examples -* Run this example - - ```nbt - >>> trunc(5.5) - - trunc(5.5) - - = 5 - - ``` -* Run this example - - ```nbt - >>> trunc(-5.5) - - trunc(-5.5) - - = -5 - - ``` +
>>> trunc(5.5)
+
+    = 5
+
+ +
>>> trunc(-5.5)
+
+    = -5
+
+
### `trunc_in` (Truncation) @@ -343,28 +258,18 @@ fn trunc_in(base: D, value: D) -> D
Examples -* Truncate in meters. - - Run this example - ```nbt - >>> trunc_in(m, 5.7 m) - - trunc_in(metre, 5.7 metre) - - = 5 m [Length] - - ``` -* Truncate in centimeters. - - Run this example - ```nbt - >>> trunc_in(cm, 5.7 m) - - trunc_in(centimetre, 5.7 metre) - - = 570 cm [Length] - - ``` +Truncate in meters. +
>>> trunc_in(m, 5.7 m)
+
+    = 5 m    [Length]
+
+ +Truncate in centimeters. +
>>> trunc_in(cm, 5.7 m)
+
+    = 570 cm    [Length]
+
+
### `mod` (Modulo) @@ -378,16 +283,11 @@ fn mod(a: T, b: T) -> T
Examples -* Run this example +
>>> mod(27, 5)
+
+    = 2
+
- ```nbt - >>> mod(27, 5) - - mod(27, 5) - - = 2 - - ```
## Transcendental functions @@ -405,16 +305,11 @@ fn exp(x: Scalar) -> Scalar
Examples -* Run this example +
>>> exp(4)
+
+    = 54.5982
+
- ```nbt - >>> exp(4) - - exp(4) - - = 54.5982 - - ```
### `ln` (Natural logarithm) @@ -428,16 +323,11 @@ fn ln(x: Scalar) -> Scalar
Examples -* Run this example +
>>> ln(20)
+
+    = 2.99573
+
- ```nbt - >>> ln(20) - - ln(20) - - = 2.99573 - - ```
### `log` (Natural logarithm) @@ -451,16 +341,11 @@ fn log(x: Scalar) -> Scalar
Examples -* Run this example +
>>> log(20)
+
+    = 2.99573
+
- ```nbt - >>> log(20) - - log(20) - - = 2.99573 - - ```
### `log10` (Common logarithm) @@ -474,16 +359,11 @@ fn log10(x: Scalar) -> Scalar
Examples -* Run this example +
>>> log10(100)
+
+    = 2
+
- ```nbt - >>> log10(100) - - log10(100) - - = 2 - - ```
### `log2` (Binary logarithm) @@ -497,16 +377,11 @@ fn log2(x: Scalar) -> Scalar
Examples -* Run this example +
>>> log2(256)
+
+    = 8
+
- ```nbt - >>> log2(256) - - log2(256) - - = 8 - - ```
### `gamma` (Gamma function) @@ -626,16 +501,11 @@ fn maximum(xs: List) -> D
Examples -* Run this example +
>>> maximum([30 cm, 2 m])
+
+    = 2 m    [Length]
+
- ```nbt - >>> maximum([30 cm, 2 m]) - - maximum([30 centimetre, 2 metre]) - - = 2 m [Length] - - ```
### `minimum` (Minimum) @@ -648,16 +518,11 @@ fn minimum(xs: List) -> D
Examples -* Run this example +
>>> minimum([30 cm, 2 m])
+
+    = 30 cm    [Length]
+
- ```nbt - >>> minimum([30 cm, 2 m]) - - minimum([30 centimetre, 2 metre]) - - = 30 cm [Length] - - ```
### `mean` (Arithmetic mean) @@ -671,16 +536,11 @@ fn mean(xs: List) -> D
Examples -* Run this example +
>>> mean([1 m, 2 m, 300 cm])
+
+    = 2 m    [Length]
+
- ```nbt - >>> mean([1 m, 2 m, 300 cm]) - - mean([1 metre, 2 metre, 300 centimetre]) - - = 2 m [Length] - - ```
### `variance` (Variance) @@ -694,16 +554,11 @@ fn variance(xs: List) -> D^2
Examples -* Run this example +
>>> variance([1 m, 2 m, 300 cm])
+
+    = 0.666667 m²    [Area]
+
- ```nbt - >>> variance([1 m, 2 m, 300 cm]) - - variance([1 metre, 2 metre, 300 centimetre]) - - = 0.666667 m² [Area] - - ```
### `stdev` (Standard deviation) @@ -717,16 +572,11 @@ fn stdev(xs: List) -> D
Examples -* Run this example +
>>> stdev([1 m, 2 m, 300 cm])
+
+    = 0.816497 m    [Length]
+
- ```nbt - >>> stdev([1 m, 2 m, 300 cm]) - - stdev([1 metre, 2 metre, 300 centimetre]) - - = 0.816497 m [Length] - - ```
### `median` (Median) @@ -740,16 +590,11 @@ fn median(xs: List) -> D
Examples -* Run this example +
>>> median([1 m, 2 m, 400 cm])
+
+    = 2 m    [Length]
+
- ```nbt - >>> median([1 m, 2 m, 400 cm]) - - median([1 metre, 2 metre, 400 centimetre]) - - = 2 m [Length] - - ```
## Random sampling, distributions @@ -859,16 +704,11 @@ fn gcd(a: Scalar, b: Scalar) -> Scalar
Examples -* Run this example +
>>> gcd(60, 42)
+
+    = 6
+
- ```nbt - >>> gcd(60, 42) - - gcd(60, 42) - - = 6 - - ```
### `lcm` (Least common multiple) @@ -882,16 +722,11 @@ fn lcm(a: Scalar, b: Scalar) -> Scalar
Examples -* Run this example +
>>> lcm(14, 4)
+
+    = 28
+
- ```nbt - >>> lcm(14, 4) - - lcm(14, 4) - - = 28 - - ```
## Numerical methods @@ -909,37 +744,21 @@ fn diff(f: Fn[(X) -> Y], x: X) -> Y / X
Examples -* Compute the derivative of \\( f(x) = x² -x -1 \\) at \\( x=1 \\). - - Run this example - ```nbt - >>> fn polynomial(x) = x² - x - 1 - diff(polynomial, 1) - - fn polynomial(x: Scalar) -> Scalar = (x² - x) - 1 - - diff(polynomial, 1) - - = 1.0 - - ``` -* Compute the free fall velocity after \\( t=2 s \\). - - Run this example - ```nbt - >>> fn distance(t) = 0.5 g0 t² - fn velocity(t) = diff(distance, t) - velocity(2 s) - - fn distance(t: A) -> A² × Length / Time² = 0.5 g0 × t² - - fn velocity(t: A) -> A × Length / Time² = diff(distance, t) - - velocity(2 second) - - = 19.6133 m/s [Velocity] - - ``` +Compute the derivative of \\( f(x) = x² -x -1 \\) at \\( x=1 \\). +
>>> fn polynomial(x) = x² - x - 1
+diff(polynomial, 1)
+
+    = 1.0
+
+ +Compute the free fall velocity after \\( t=2 s \\). +
>>> fn distance(t) = 0.5 g0 t²
+fn velocity(t) = diff(distance, t)
+velocity(2 s)
+
+    = 19.6133 m/s    [Velocity]
+
+
### `root_bisect` (Bisection method) @@ -953,20 +772,13 @@ fn root_bisect(f: Fn[(X) -> Y], x1: X, x2: X, x_tol: X, y_tol: Y
Examples -* Find the root of \\( f(x) = x² +x -2 \\) in the interval \\( [0, 100] \\). - - Run this example - ```nbt - >>> fn f(x) = x² +x -2 - root_bisect(f, 0, 100, 0.01, 0.01) - - fn f(x: Scalar) -> Scalar = (x² + x) - 2 - - root_bisect(f, 0, 100, 0.01, 0.01) - - = 1.00098 - - ``` +Find the root of \\( f(x) = x² +x -2 \\) in the interval \\( [0, 100] \\). +
>>> fn f(x) = x² +x -2
+root_bisect(f, 0, 100, 0.01, 0.01)
+
+    = 1.00098
+
+
### `root_newton` (Newton's method) @@ -980,23 +792,14 @@ fn root_newton(f: Fn[(X) -> Y], f_prime: Fn[(X) -> Y / X], x0: X
Examples -* Find a root of \\( f(x) = x² -3x +2 \\) using Newton's method. - - Run this example - ```nbt - >>> fn f(x) = x² -3x +2 - fn f_prime(x) = 2x -3 - root_newton(f, f_prime, 0 , 0.01) - - fn f(x: Scalar) -> Scalar = (x² - 3 x) + 2 - - fn f_prime(x: Scalar) -> Scalar = 2 x - 3 - - root_newton(f, f_prime, 0, 0.01) - - = 0.996078 - - ``` +Find a root of \\( f(x) = x² -3x +2 \\) using Newton's method. +
>>> fn f(x) = x² -3x +2
+fn f_prime(x) = 2x -3
+root_newton(f, f_prime, 0 , 0.01)
+
+    = 0.996078
+
+
### `fixed_point` (Fixed-point iteration) @@ -1010,20 +813,13 @@ fn fixed_point(f: Fn[(X) -> X], x0: X, ε: X) -> X
Examples -* Compute the fixed poin of \\( f(x) = x/2 -1 \\). - - Run this example - ```nbt - >>> fn function(x) = x/2 - 1 - fixed_point(function, 0, 0.01) - - fn function(x: Scalar) -> Scalar = (x / 2) - 1 - - fixed_point(function, 0, 0.01) - - = -1.99219 - - ``` +Compute the fixed poin of \\( f(x) = x/2 -1 \\). +
>>> fn function(x) = x/2 - 1
+fixed_point(function, 0, 0.01)
+
+    = -1.99219
+
+
## Geometry @@ -1040,16 +836,11 @@ fn hypot2(x: T, y: T) -> T
Examples -* Run this example +
>>> hypot2(3 m, 4 m)
+
+    = 5 m    [Length]
+
- ```nbt - >>> hypot2(3 m, 4 m) - - hypot2(3 metre, 4 metre) - - = 5 m [Length] - - ```
### `hypot3` @@ -1062,16 +853,11 @@ fn hypot3(x: T, y: T, z: T) -> T
Examples -* Run this example +
>>> hypot3(8, 9, 12)
+
+    = 17
+
- ```nbt - >>> hypot3(8, 9, 12) - - hypot3(8, 9, 12) - - = 17 - - ```
### `circle_area` @@ -1117,17 +903,12 @@ fn quadratic_equation(a: A, b: B, c: B^2 / A) -> List
Examples -* Solve the equation \\( 2x² -x -1 = 0 \\) - - Run this example - ```nbt - >>> quadratic_equation(2, -1, -1) - - quadratic_equation(2, -1, -1) - - = [1, -0.5] [List] - - ``` +Solve the equation \\( 2x² -x -1 = 0 \\) +
>>> quadratic_equation(2, -1, -1)
+
+    = [1, -0.5]    [List]
+
+
## Trigonometry (extra) diff --git a/book/src/list-functions-other.md b/book/src/list-functions-other.md index 804d93c4..71ba20c6 100644 --- a/book/src/list-functions-other.md +++ b/book/src/list-functions-other.md @@ -28,26 +28,16 @@ fn is_nan(n: T) -> Bool
Examples -* Run this example - - ```nbt - >>> is_nan(37) - - is_nan(37) - - = false [Bool] - - ``` -* Run this example - - ```nbt - >>> is_nan(NaN) - - is_nan(NaN) - - = true [Bool] - - ``` +
>>> is_nan(37)
+
+    = false    [Bool]
+
+ +
>>> is_nan(NaN)
+
+    = true    [Bool]
+
+
### `is_infinite` @@ -61,26 +51,16 @@ fn is_infinite(n: T) -> Bool
Examples -* Run this example - - ```nbt - >>> is_infinite(37) - - is_infinite(37) - - = false [Bool] - - ``` -* Run this example - - ```nbt - >>> is_infinite(-inf) - - is_infinite(-inf) - - = true [Bool] - - ``` +
>>> is_infinite(37)
+
+    = false    [Bool]
+
+ +
>>> is_infinite(-inf)
+
+    = true    [Bool]
+
+
### `is_finite` @@ -93,26 +73,16 @@ fn is_finite(n: T) -> Bool
Examples -* Run this example - - ```nbt - >>> is_finite(37) - - is_finite(37) - - = true [Bool] - - ``` -* Run this example - - ```nbt - >>> is_finite(-inf) - - is_finite(-inf) - - = false [Bool] - - ``` +
>>> is_finite(37)
+
+    = true    [Bool]
+
+ +
>>> is_finite(-inf)
+
+    = false    [Bool]
+
+
## Quantities @@ -129,16 +99,11 @@ fn unit_of(x: T) -> T
Examples -* Run this example +
>>> unit_of(20 km/h)
+
+    = 1 km/h    [Velocity]
+
- ```nbt - >>> unit_of(20 km/h) - - unit_of(20 kilometre / hour) - - = 1 km/h [Velocity] - - ```
### `value_of` @@ -151,16 +116,11 @@ fn value_of(x: T) -> Scalar
Examples -* Run this example +
>>> value_of(20 km/h)
+
+    = 20
+
- ```nbt - >>> value_of(20 km/h) - - value_of(20 kilometre / hour) - - = 20 - - ```
## Chemical elements @@ -177,28 +137,18 @@ fn element(pattern: String) -> ChemicalElement
Examples -* Get the entire element struct for hydrogen. - - Run this example - ```nbt - >>> element("H") - - element("H") - - = ChemicalElement { symbol: "H", name: "Hydrogen", atomic_number: 1, group: 1, group_name: "Alkali metals", period: 1, melting_point: 13.99 K, boiling_point: 20.271 K, density: 0.00008988 g/cm³, electron_affinity: 0.754 eV, ionization_energy: 13.598 eV, vaporization_heat: 0.904 kJ/mol } [ChemicalElement] - - ``` -* Get the ionization energy of hydrogen. - - Run this example - ```nbt - >>> element("hydrogen").ionization_energy - - element("hydrogen").ionization_energy - - = 13.598 eV [Energy or Torque] - - ``` +Get the entire element struct for hydrogen. +
>>> element("H")
+
+    = ChemicalElement { symbol: "H", name: "Hydrogen", atomic_number: 1, group: 1, group_name: "Alkali metals", period: 1, melting_point: 13.99 K, boiling_point: 20.271 K, density: 0.00008988 g/cm³, electron_affinity: 0.754 eV, ionization_energy: 13.598 eV, vaporization_heat: 0.904 kJ/mol }    [ChemicalElement]
+
+ +Get the ionization energy of hydrogen. +
>>> element("hydrogen").ionization_energy
+
+    = 13.598 eV    [Energy or Torque]
+
+
## Mixed unit conversion @@ -216,16 +166,11 @@ fn DMS(alpha: Angle) -> String
Examples -* Run this example +
>>> 46.5858° -> DMS
+
+    = "46° 35′ 9″"    [String]
+
- ```nbt - >>> 46.5858° -> DMS - - DMS(46.5858 degree) - - = "46° 35′ 9″" [String] - - ```
### `DM` (Degrees, decimal minutes) @@ -239,16 +184,11 @@ fn DM(alpha: Angle) -> String
Examples -* Run this example +
>>> 46.5858° -> DM
+
+    = "46° 35.148′"    [String]
+
- ```nbt - >>> 46.5858° -> DM - - DM(46.5858 degree) - - = "46° 35.148′" [String] - - ```
### `feet_and_inches` (Feet and inches) @@ -262,16 +202,11 @@ fn feet_and_inches(length: Length) -> String
Examples -* Run this example +
>>> 180 cm -> feet_and_inches
+
+    = "5 ft 10.8661 in"    [String]
+
- ```nbt - >>> 180 cm -> feet_and_inches - - feet_and_inches(180 centimetre) - - = "5 ft 10.8661 in" [String] - - ```
### `pounds_and_ounces` (Pounds and ounces) @@ -285,16 +220,11 @@ fn pounds_and_ounces(mass: Mass) -> String
Examples -* Run this example +
>>> 1 kg -> pounds_and_ounces
+
+    = "2 lb 3.27396 oz"    [String]
+
- ```nbt - >>> 1 kg -> pounds_and_ounces - - pounds_and_ounces(1 kilogram) - - = "2 lb 3.27396 oz" [String] - - ```
## Temperature conversion @@ -312,17 +242,12 @@ fn from_celsius(t_celsius: Scalar) -> Temperature
Examples -* 300 °C in Kelvin. - - Run this example - ```nbt - >>> from_celsius(300) - - from_celsius(300) - - = 573.15 K [Temperature] - - ``` +300 °C in Kelvin. +
>>> from_celsius(300)
+
+    = 573.15 K    [Temperature]
+
+
### `celsius` @@ -336,17 +261,12 @@ fn celsius(t_kelvin: Temperature) -> Scalar
Examples -* 300 K in degree Celsius. - - Run this example - ```nbt - >>> 300K -> celsius - - celsius(300 kelvin) - - = 26.85 - - ``` +300 K in degree Celsius. +
>>> 300K -> celsius
+
+    = 26.85
+
+
### `from_fahrenheit` @@ -360,17 +280,12 @@ fn from_fahrenheit(t_fahrenheit: Scalar) -> Temperature
Examples -* 300 °F in Kelvin. - - Run this example - ```nbt - >>> from_fahrenheit(300) - - from_fahrenheit(300) - - = 422.039 K [Temperature] - - ``` +300 °F in Kelvin. +
>>> from_fahrenheit(300)
+
+    = 422.039 K    [Temperature]
+
+
### `fahrenheit` @@ -384,17 +299,12 @@ fn fahrenheit(t_kelvin: Temperature) -> Scalar
Examples -* 300 K in degree Fahrenheit. - - Run this example - ```nbt - >>> 300K -> fahrenheit - - fahrenheit(300 kelvin) - - = 80.33 - - ``` +300 K in degree Fahrenheit. +
>>> 300K -> fahrenheit
+
+    = 80.33
+
+
## Color format conversion @@ -411,16 +321,11 @@ fn rgb(red: Scalar, green: Scalar, blue: Scalar) -> Color
Examples -* Run this example +
>>> rgb(125, 128, 218)
+
+    = Color { red: 125, green: 128, blue: 218 }    [Color]
+
- ```nbt - >>> rgb(125, 128, 218) - - rgb(125, 128, 218) - - = Color { red: 125, green: 128, blue: 218 } [Color] - - ```
### `color` @@ -433,16 +338,11 @@ fn color(rgb_hex: Scalar) -> Color
Examples -* Run this example +
>>> color(0xff7700)
+
+    = Color { red: 255, green: 119, blue: 0 }    [Color]
+
- ```nbt - >>> color(0xff7700) - - color(16_742_144) - - = Color { red: 255, green: 119, blue: 0 } [Color] - - ```
### `color_rgb` @@ -455,16 +355,11 @@ fn color_rgb(color: Color) -> String
Examples -* Run this example +
>>> cyan -> color_rgb
+
+    = "rgb(0, 255, 255)"    [String]
+
- ```nbt - >>> cyan -> color_rgb - - color_rgb(cyan) - - = "rgb(0, 255, 255)" [String] - - ```
### `color_rgb_float` @@ -477,16 +372,11 @@ fn color_rgb_float(color: Color) -> String
Examples -* Run this example +
>>> cyan -> color_rgb_float
+
+    = "rgb(0.000, 1.000, 1.000)"    [String]
+
- ```nbt - >>> cyan -> color_rgb_float - - color_rgb_float(cyan) - - = "rgb(0.000, 1.000, 1.000)" [String] - - ```
### `color_hex` @@ -499,15 +389,10 @@ fn color_hex(color: Color) -> String
Examples -* Run this example +
>>> rgb(225, 36, 143) -> color_hex
+
+    = "#e1248f"    [String]
+
- ```nbt - >>> rgb(225, 36, 143) -> color_hex - - color_hex(rgb(225, 36, 143)) - - = "#e1248f" [String] - - ```
diff --git a/book/src/list-functions-strings.md b/book/src/list-functions-strings.md index 59df2308..c233d39b 100644 --- a/book/src/list-functions-strings.md +++ b/book/src/list-functions-strings.md @@ -12,16 +12,11 @@ fn str_length(s: String) -> Scalar
Examples -* Run this example - - ```nbt - >>> str_length("Numbat") - - str_length("Numbat") - - = 6 - - ``` +
>>> str_length("Numbat")
+
+    = 6
+
+
### `str_slice` @@ -34,16 +29,11 @@ fn str_slice(s: String, start: Scalar, end: Scalar) -> String
Examples -* Run this example +
>>> str_slice("Numbat", 3, 6)
+
+    = "bat"    [String]
+
- ```nbt - >>> str_slice("Numbat", 3, 6) - - str_slice("Numbat", 3, 6) - - = "bat" [String] - - ```
### `chr` @@ -56,16 +46,11 @@ fn chr(n: Scalar) -> String
Examples -* Run this example +
>>> 0x2764 -> chr
+
+    = "❤"    [String]
+
- ```nbt - >>> 0x2764 -> chr - - chr(10084) - - = "❤" [String] - - ```
### `ord` @@ -78,16 +63,11 @@ fn ord(s: String) -> Scalar
Examples -* Run this example +
>>> "❤" -> ord
+
+    = 10084
+
- ```nbt - >>> "❤" -> ord - - ord("❤") - - = 10084 - - ```
### `lowercase` @@ -100,16 +80,11 @@ fn lowercase(s: String) -> String
Examples -* Run this example +
>>> lowercase("Numbat")
+
+    = "numbat"    [String]
+
- ```nbt - >>> lowercase("Numbat") - - lowercase("Numbat") - - = "numbat" [String] - - ```
### `uppercase` @@ -122,16 +97,11 @@ fn uppercase(s: String) -> String
Examples -* Run this example +
>>> uppercase("Numbat")
+
+    = "NUMBAT"    [String]
+
- ```nbt - >>> uppercase("Numbat") - - uppercase("Numbat") - - = "NUMBAT" [String] - - ```
### `str_append` @@ -144,16 +114,11 @@ fn str_append(a: String, b: String) -> String
Examples -* Run this example +
>>> str_append("Numbat", "!")
+
+    = "Numbat!"    [String]
+
- ```nbt - >>> str_append("Numbat", "!") - - str_append("Numbat", "!") - - = "Numbat!" [String] - - ```
### `str_find` @@ -166,16 +131,11 @@ fn str_find(haystack: String, needle: String) -> Scalar
Examples -* Run this example +
>>> str_find("Numbat is a statically typed programming language.", "typed")
+
+    = 23
+
- ```nbt - >>> str_find("Numbat is a statically typed programming language.", "typed") - - str_find("Numbat is a statically typed programming language.", "typed") - - = 23 - - ```
### `str_contains` @@ -188,16 +148,11 @@ fn str_contains(haystack: String, needle: String) -> Bool
Examples -* Run this example +
>>> str_contains("Numbat is a statically typed programming language.", "typed")
+
+    = true    [Bool]
+
- ```nbt - >>> str_contains("Numbat is a statically typed programming language.", "typed") - - str_contains("Numbat is a statically typed programming language.", "typed") - - = true [Bool] - - ```
### `str_replace` @@ -210,16 +165,11 @@ fn str_replace(s: String, pattern: String, replacement: String) -> String
Examples -* Run this example +
>>> str_replace("Numbat is a statically typed programming language.", "statically typed programming language", "scientific calculator")
+
+    = "Numbat is a scientific calculator."    [String]
+
- ```nbt - >>> str_replace("Numbat is a statically typed programming language.", "statically typed programming language", "scientific calculator") - - str_replace("Numbat is a statically typed programming language.", "statically typed programming language", "scientific calculator") - - = "Numbat is a scientific calculator." [String] - - ```
### `str_repeat` @@ -232,16 +182,11 @@ fn str_repeat(a: String, n: Scalar) -> String
Examples -* Run this example +
>>> str_repeat("abc", 4)
+
+    = "abcabcabcabc"    [String]
+
- ```nbt - >>> str_repeat("abc", 4) - - str_repeat("abc", 4) - - = "abcabcabcabc" [String] - - ```
### `base` @@ -254,16 +199,11 @@ fn base(b: Scalar, x: Scalar) -> String
Examples -* Run this example +
>>> 42 |> base(16)
+
+    = "2a"    [String]
+
- ```nbt - >>> 42 |> base(16) - - base(16, 42) - - = "2a" [String] - - ```
### `bin` @@ -276,16 +216,11 @@ fn bin(x: Scalar) -> String
Examples -* Run this example +
>>> 42 -> bin
+
+    = "0b101010"    [String]
+
- ```nbt - >>> 42 -> bin - - bin(42) - - = "0b101010" [String] - - ```
### `oct` @@ -298,16 +233,11 @@ fn oct(x: Scalar) -> String
Examples -* Run this example +
>>> 42 -> oct
+
+    = "0o52"    [String]
+
- ```nbt - >>> 42 -> oct - - oct(42) - - = "0o52" [String] - - ```
### `dec` @@ -320,16 +250,11 @@ fn dec(x: Scalar) -> String
Examples -* Run this example +
>>> 0b111 -> dec
+
+    = "7"    [String]
+
- ```nbt - >>> 0b111 -> dec - - dec(7) - - = "7" [String] - - ```
### `hex` @@ -342,15 +267,10 @@ fn hex(x: Scalar) -> String
Examples -* Run this example +
>>> 2^31-1 -> hex
+
+    = "0x7fffffff"    [String]
+
- ```nbt - >>> 2^31-1 -> hex - - hex(2^31 - 1) - - = "0x7fffffff" [String] - - ```
diff --git a/numbat/examples/inspect.rs b/numbat/examples/inspect.rs index c046d057..0edd14f0 100644 --- a/numbat/examples/inspect.rs +++ b/numbat/examples/inspect.rs @@ -1,7 +1,6 @@ use itertools::Itertools; use numbat::markup::plain_text_format; use numbat::module_importer::FileSystemImporter; -use numbat::pretty_print::PrettyPrint; use numbat::resolver::CodeSource; use numbat::Context; use percent_encoding; @@ -117,48 +116,36 @@ fn inspect_functions_in_module(ctx: &Context, prelude_ctx: &Context, module: Str ); //Assemble the example output - let mut example_output = String::new(); - example_output += "\n"; - - for statement in &statements { - example_output += &plain_text_format(&statement.pretty_print(), true); - example_output += "\n\n"; - } - let result_markup = results.to_markup( statements.last(), &example_ctx.dimension_registry(), true, true, ); - example_output += &plain_text_format(&result_markup, false); - - if results.is_value() { - example_output += "\n"; - } + let example_output = &plain_text_format(&result_markup, false); //Print the example if let Some(example_description) = example_description { - println!( - "* {}\n\n Run this example", - replace_equation_delimiters(example_description), - example_url - ); - } else { - println!( - "* Run this example\n", - example_url - ); + println!("{}", replace_equation_delimiters(example_description)); } - println!(" ```nbt"); + print!("
");
+                    print!("
");
+                    print!("",
+                        "Run this code",
+                        "Run this code",
+                        example_url);
+                    print!("
");
+                    print!("");
                     for l in example_input.lines() {
-                        println!("    {}", l);
+                        println!("{}", l);
                     }
+                    println!();
                     for l in example_output.lines() {
-                        println!("    {}", l);
+                        println!("{}", l);
                     }
-                    println!("  ```");
+                    println!("
"); + println!(); } else { eprintln!( "Warning: Example \"{example_code}\" of function {fn_name} did not run successfully."