Skip to content

Std.Experimental

Defined in std-experimental@0.4.0

The module Std.Experimental contains additions to Std whose design is not settled yet. Anything here may change or be removed in any version. When its design settles, it moves into Std.

String::format fills the placeholders {} of a template with values of any types that implement Format. A wrapper such as with_precision or right_aligned_to changes how a value is written, and one wrapper can wrap another:

let name = "pi".left_aligned_to(4);
let value = 3.14159.with_precision(2_U8).right_aligned_to(6);
assert_eq(|_|"", "{}|{}".format((name, value)), "pi  |  3.14")

Format and FormatArgs are implemented for tuples of up to 12 elements.

Slice is a part of an array, and StringSlice is a part of a string. Taking one does not copy the elements:

assert_eq(|_|"", [1, 2, 3, 4].get_slice(1, 3).to_array, [2, 3]);;
assert_eq(|_|"", "abc,def".get_slice(4, 7).to_string, "def")

Values

namespace Std.Experimental::Array

get_slice

Type: Std::I64 -> Std::I64 -> Std::Array a -> Std.Experimental::Slice a

A slice of the elements of array from index begin up to index end. It is like get_sub, but does not copy the elements.

begin and end are clamped to [0, array.@size]. If end <= begin, the slice is empty.

Examples
assert_eq(|_|"", [1, 2, 3, 4].get_slice(1, 3).to_array, [2, 3])
Parameters
  • begin - The index of the first element.
  • end - The index after the last element.
  • array - The array.

to_slice

Type: Std::Array a -> Std.Experimental::Slice a

A slice of all the elements of array.

Parameters
  • array - The array.

with_separator

Type: Std::String -> Std::Array a -> Std.Experimental::Format::WithSeparator a

Wraps elements so that format writes them with separator between them.

Examples
assert_eq(|_|"", "{}".format(([1, 2, 3].with_separator(", "),)), "1, 2, 3")
Parameters
  • separator - The text to write between two elements.
  • elements - The elements.

namespace Std.Experimental::F32

with_precision

Type: Std::U8 -> Std::F32 -> Std.Experimental::Format::WithPrecision Std::F32

Wraps v so that format writes it with precision digits after the decimal point, as F32::to_string_precision does.

Examples
assert_eq(|_|"", "{}".format((3.14159_F32.with_precision(2_U8),)), "3.14")
Parameters
  • precision - The number of digits after the decimal point.
  • v - The number.

namespace Std.Experimental::F64

with_precision

Type: Std::U8 -> Std::F64 -> Std.Experimental::Format::WithPrecision Std::F64

Wraps v so that format writes it with precision digits after the decimal point, as F64::to_string_precision does.

Examples
assert_eq(|_|"", "{}".format((3.14159.with_precision(2_U8),)), "3.14")
Parameters
  • precision - The number of digits after the decimal point.
  • v - The number.

namespace Std.Experimental::Format

left_aligned_to

Type: Std::I64 -> a -> Std.Experimental::Format::LeftAligned a

Wraps value so that format pads its text with spaces on the right to width Unicode code points. A text that already has width code points or more is written unchanged.

Examples
assert_eq(|_|"", "[{}]".format((42.left_aligned_to(5),)), "[42   ]")
Parameters
  • width - The minimum width, in Unicode code points.
  • value - The value to write.

right_aligned_to

Type: Std::I64 -> a -> Std.Experimental::Format::RightAligned a

Wraps value so that format pads its text with spaces on the left to width Unicode code points. A text that already has width code points or more is written unchanged.

Examples
assert_eq(|_|"", "[{}]".format((42.right_aligned_to(5),)), "[   42]")
Parameters
  • width - The minimum width, in Unicode code points.
  • value - The value to write.

write_text

Type: [a : Std.Experimental::Format] a -> Std.Experimental::Format::TextOut -> Std.Experimental::Format::TextOut

Trait member of Std.Experimental::Format

Appends the text of value to out.

Parameters
  • value - The value to write.
  • out - The text written so far.

namespace Std.Experimental::FormatArgs

write_args

Type: [args : Std.Experimental::FormatArgs] args -> Std.Experimental::FormatArgs::TemplateCursor -> Std.Experimental::FormatArgs::TemplateCursor

Trait member of Std.Experimental::FormatArgs

Writes each value into the next placeholder of the template, after the template text before that placeholder.

Parameters
  • values - The values.
  • cursor - The template and how much of it has been written.

namespace Std.Experimental::Slice

@

Type: Std::I64 -> Std.Experimental::Slice a -> a

The element at index i of slice. Index 0 is the first element of the slice. The program aborts if i is out of range.

Parameters
  • i - The index.
  • slice - The slice.

@array

Type: Std.Experimental::Slice a -> Std::Array a

The whole array that slice was taken from. The elements of slice are the elements of this array from index @begin up to index @end.

Parameters
  • slice - The slice.

@begin

Type: Std.Experimental::Slice a -> Std::I64

The index in @array of the first element of slice.

Parameters
  • slice - The slice.

@end

Type: Std.Experimental::Slice a -> Std::I64

The index in @array after the last element of slice.

Parameters
  • slice - The slice.

@size

Type: Std.Experimental::Slice a -> Std::I64

The number of elements of slice.

Parameters
  • slice - The slice.

get_slice

Type: Std::I64 -> Std::I64 -> Std.Experimental::Slice a -> Std.Experimental::Slice a

A slice of the elements of slice from index begin up to index end. Index 0 is the first element of slice.

begin and end are clamped to [0, slice.@size]. If end <= begin, the slice is empty.

Examples
let slice = [1, 2, 3, 4, 5].get_slice(1, 5);   // [2, 3, 4, 5]
assert_eq(|_|"", slice.get_slice(1, 3).to_array, [3, 4])
Parameters
  • begin - The index of the first element.
  • end - The index after the last element.
  • slice - The slice.

to_array

Type: Std.Experimental::Slice a -> Std::Array a

Copies the elements of slice into a new array.

Parameters
  • slice - The slice.

to_iter

Type: [?it : Std::Iterator, Std::Iterator::Item ?it = a] Std.Experimental::Slice a -> ?it

An iterator over the elements of slice.

Parameters
  • slice - The slice.

with_separator

Type: Std::String -> Std.Experimental::Slice a -> Std.Experimental::Format::WithSeparator a

Wraps elements so that format writes them with separator between them.

Examples
assert_eq(|_|"", "{}".format(([1, 2, 3, 4].get_slice(1, 4).with_separator("-"),)), "2-3-4")
Parameters
  • separator - The text to write between two elements.
  • elements - The elements.

namespace Std.Experimental::String

format

Type: [args : Std.Experimental::FormatArgs] args -> Std::String -> Std::String

Replaces the placeholders {} in a template with values.

Each {} is replaced with the text of the next value, as Format writes it. {{ and }} are written as { and }.

Pass the values as a tuple. The values may have different types. Write (x,) for one value and () for none.

The program aborts if the number of placeholders differs from the number of values, or if the template has a { or } that is not part of a placeholder or an escape.

Examples
assert_eq(|_|"", "{} + {} = {}".format((1, 2.5, "three")), "1 + 2.5 = three");;
assert_eq(|_|"", "x = {}".format((42,)), "x = 42");;
assert_eq(|_|"", "{{{}}}".format((1,)), "{1}")
Parameters
  • values - The values to write, in order.
  • template - The template.

get_slice

Type: Std::I64 -> Std::I64 -> Std::String -> Std.Experimental::StringSlice

A slice of the bytes of str from index begin up to index end. It is like get_sub, but does not copy the bytes.

begin and end are clamped to [0, str.@size]. If end <= begin, the slice is empty.

Examples
assert_eq(|_|"", "abc,def".get_slice(4, 7).to_string, "def")
Parameters
  • begin - The index of the first byte.
  • end - The index after the last byte.
  • str - The string.

to_slice

Type: Std::String -> Std.Experimental::StringSlice

A slice of all the bytes of str.

Parameters
  • str - The string.

namespace Std.Experimental::StringSlice

@size

Type: Std.Experimental::StringSlice -> Std::I64

The number of bytes of slice.

Parameters
  • slice - The string slice.

get_bytes

Type: Std.Experimental::StringSlice -> Std.Experimental::Slice Std::U8

The bytes of slice as a Slice U8. It does not copy the bytes.

Examples
assert_eq(|_|"", "abc,def".get_slice(4, 7).get_bytes.to_array, ['d', 'e', 'f'])
Parameters
  • slice - The string slice.

get_slice

Type: Std::I64 -> Std::I64 -> Std.Experimental::StringSlice -> Std.Experimental::StringSlice

A slice of the bytes of slice from index begin up to index end. Index 0 is the first byte of slice.

begin and end are clamped to [0, slice.@size]. If end <= begin, the slice is empty.

Examples
let slice = "abc,def".get_slice(4, 7);   // def
assert_eq(|_|"", slice.get_slice(1, 3).to_string, "ef")
Parameters
  • begin - The index of the first byte.
  • end - The index after the last byte.
  • slice - The string slice.

Types and aliases

namespace Std.Experimental

Slice

Defined as: type Slice a = unbox struct { ...fields... }

A part of an array: the elements from one index up to another. Taking a slice does not copy the elements.

Create a slice with Array::to_slice or Array::get_slice. For a part of a string, use StringSlice.

to_string and format write a slice the same way as an array: [1, 2, 3].

A slice keeps a reference to the array it was taken from. While the slice exists, modifying that array copies it.

StringSlice

Defined as: type StringSlice = unbox struct { ...fields... }

A part of a string: the bytes from one index up to another. Taking a string slice does not copy the bytes.

Create a string slice with String::to_slice or String::get_slice.

to_string and format write a string slice as its text:

let slice = "abc,def".get_slice(4, 7);
assert_eq(|_|"", slice.to_string, "def");;
assert_eq(|_|"", "[{}]".format((slice.right_aligned_to(5),)), "[  def]")

A string slice keeps a reference to the string it was taken from.

namespace Std.Experimental::Format

LeftAligned

Defined as: type LeftAligned a = unbox struct { ...fields... }

A value padded with spaces on the right to a width. Created by left_aligned_to.

RightAligned

Defined as: type RightAligned a = unbox struct { ...fields... }

A value padded with spaces on the left to a width. Created by right_aligned_to.

TextOut

Defined as: type TextOut = unbox struct { ...fields... }

The text written so far. Format::write_text appends the text of a value to it.

WithPrecision

Defined as: type WithPrecision a = unbox struct { ...fields... }

A floating-point number written with a fixed number of digits after the decimal point. Created by F32::with_precision or F64::with_precision.

WithSeparator

Defined as: type WithSeparator a = unbox struct { ...fields... }

The elements of an array or of a slice, written with a separator between them. Created by with_separator.

namespace Std.Experimental::FormatArgs

TemplateCursor

Defined as: type TemplateCursor = unbox struct { ...fields... }

A template that format is filling in: the template, the position up to which it has been written, and the text written so far.

Traits and aliases

namespace Std.Experimental

trait a : Format

A type whose values format can write.

If the type also implements ToString, write_text must write the same text as to_string.

A type that implements ToString can implement Format in one line:

impl Point : Format {
    write_text = |p, out| out.write_text(p.to_string);
}

Writing each part directly is faster, because it creates no intermediate string:

impl Point : Format {
    write_text = |p, out| out.write_text("(").write_text(p.@x).write_text(", ").write_text(p.@y).write_text(")");
}
method write_text

Type: a -> Std.Experimental::Format::TextOut -> Std.Experimental::Format::TextOut

Appends the text of value to out.

Parameters
  • value - The value to write.
  • out - The text written so far.

trait args : FormatArgs

The values that format writes into a template: (), or a tuple of values whose types implement Format.

method write_args

Type: args -> Std.Experimental::FormatArgs::TemplateCursor -> Std.Experimental::FormatArgs::TemplateCursor

Writes each value into the next placeholder of the template, after the template text before that placeholder.

Parameters
  • values - The values.
  • cursor - The template and how much of it has been written.

Trait implementations

impl () : Std.Experimental::Format

Writes (), as to_string does.

impl () : Std.Experimental::FormatArgs

impl [t0 : Std.Experimental::Format, t1 : Std.Experimental::Format] (t0, t1) : Std.Experimental::Format

impl [t0 : Std.Experimental::Format, t1 : Std.Experimental::Format] (t0, t1) : Std.Experimental::FormatArgs

impl [t0 : Std.Experimental::Format, t1 : Std.Experimental::Format, t2 : Std.Experimental::Format] (t0, t1, t2) : Std.Experimental::Format

impl [t0 : Std.Experimental::Format, t1 : Std.Experimental::Format, t2 : Std.Experimental::Format] (t0, t1, t2) : Std.Experimental::FormatArgs

impl [t0 : Std.Experimental::Format, t1 : Std.Experimental::Format, t2 : Std.Experimental::Format, t3 : Std.Experimental::Format] (t0, t1, t2, t3) : Std.Experimental::Format

impl [t0 : Std.Experimental::Format, t1 : Std.Experimental::Format, t2 : Std.Experimental::Format, t3 : Std.Experimental::Format] (t0, t1, t2, t3) : Std.Experimental::FormatArgs

impl [t0 : Std.Experimental::Format, t1 : Std.Experimental::Format, t2 : Std.Experimental::Format, t3 : Std.Experimental::Format, t4 : Std.Experimental::Format] (t0, t1, t2, t3, t4) : Std.Experimental::Format

impl [t0 : Std.Experimental::Format, t1 : Std.Experimental::Format, t2 : Std.Experimental::Format, t3 : Std.Experimental::Format, t4 : Std.Experimental::Format] (t0, t1, t2, t3, t4) : Std.Experimental::FormatArgs

impl [t0 : Std.Experimental::Format, t1 : Std.Experimental::Format, t2 : Std.Experimental::Format, t3 : Std.Experimental::Format, t4 : Std.Experimental::Format, t5 : Std.Experimental::Format] (t0, t1, t2, t3, t4, t5) : Std.Experimental::Format

impl [t0 : Std.Experimental::Format, t1 : Std.Experimental::Format, t2 : Std.Experimental::Format, t3 : Std.Experimental::Format, t4 : Std.Experimental::Format, t5 : Std.Experimental::Format] (t0, t1, t2, t3, t4, t5) : Std.Experimental::FormatArgs

impl [t0 : Std.Experimental::Format, t1 : Std.Experimental::Format, t2 : Std.Experimental::Format, t3 : Std.Experimental::Format, t4 : Std.Experimental::Format, t5 : Std.Experimental::Format, t6 : Std.Experimental::Format] (t0, t1, t2, t3, t4, t5, t6) : Std.Experimental::Format

impl [t0 : Std.Experimental::Format, t1 : Std.Experimental::Format, t2 : Std.Experimental::Format, t3 : Std.Experimental::Format, t4 : Std.Experimental::Format, t5 : Std.Experimental::Format, t6 : Std.Experimental::Format] (t0, t1, t2, t3, t4, t5, t6) : Std.Experimental::FormatArgs

impl [t0 : Std.Experimental::Format, t1 : Std.Experimental::Format, t2 : Std.Experimental::Format, t3 : Std.Experimental::Format, t4 : Std.Experimental::Format, t5 : Std.Experimental::Format, t6 : Std.Experimental::Format, t7 : Std.Experimental::Format] (t0, t1, t2, t3, t4, t5, t6, t7) : Std.Experimental::Format

impl [t0 : Std.Experimental::Format, t1 : Std.Experimental::Format, t2 : Std.Experimental::Format, t3 : Std.Experimental::Format, t4 : Std.Experimental::Format, t5 : Std.Experimental::Format, t6 : Std.Experimental::Format, t7 : Std.Experimental::Format] (t0, t1, t2, t3, t4, t5, t6, t7) : Std.Experimental::FormatArgs

impl [t0 : Std.Experimental::Format, t1 : Std.Experimental::Format, t2 : Std.Experimental::Format, t3 : Std.Experimental::Format, t4 : Std.Experimental::Format, t5 : Std.Experimental::Format, t6 : Std.Experimental::Format, t7 : Std.Experimental::Format, t8 : Std.Experimental::Format] (t0, t1, t2, t3, t4, t5, t6, t7, t8) : Std.Experimental::Format

impl [t0 : Std.Experimental::Format, t1 : Std.Experimental::Format, t2 : Std.Experimental::Format, t3 : Std.Experimental::Format, t4 : Std.Experimental::Format, t5 : Std.Experimental::Format, t6 : Std.Experimental::Format, t7 : Std.Experimental::Format, t8 : Std.Experimental::Format] (t0, t1, t2, t3, t4, t5, t6, t7, t8) : Std.Experimental::FormatArgs

impl [t0 : Std.Experimental::Format, t1 : Std.Experimental::Format, t2 : Std.Experimental::Format, t3 : Std.Experimental::Format, t4 : Std.Experimental::Format, t5 : Std.Experimental::Format, t6 : Std.Experimental::Format, t7 : Std.Experimental::Format, t8 : Std.Experimental::Format, t9 : Std.Experimental::Format] (t0, t1, t2, t3, t4, t5, t6, t7, t8, t9) : Std.Experimental::Format

impl [t0 : Std.Experimental::Format, t1 : Std.Experimental::Format, t2 : Std.Experimental::Format, t3 : Std.Experimental::Format, t4 : Std.Experimental::Format, t5 : Std.Experimental::Format, t6 : Std.Experimental::Format, t7 : Std.Experimental::Format, t8 : Std.Experimental::Format, t9 : Std.Experimental::Format] (t0, t1, t2, t3, t4, t5, t6, t7, t8, t9) : Std.Experimental::FormatArgs

impl [t0 : Std.Experimental::Format, t1 : Std.Experimental::Format, t2 : Std.Experimental::Format, t3 : Std.Experimental::Format, t4 : Std.Experimental::Format, t5 : Std.Experimental::Format, t6 : Std.Experimental::Format, t7 : Std.Experimental::Format, t8 : Std.Experimental::Format, t9 : Std.Experimental::Format, t10 : Std.Experimental::Format] (t0, t1, t2, t3, t4, t5, t6, t7, t8, t9, t10) : Std.Experimental::Format

impl [t0 : Std.Experimental::Format, t1 : Std.Experimental::Format, t2 : Std.Experimental::Format, t3 : Std.Experimental::Format, t4 : Std.Experimental::Format, t5 : Std.Experimental::Format, t6 : Std.Experimental::Format, t7 : Std.Experimental::Format, t8 : Std.Experimental::Format, t9 : Std.Experimental::Format, t10 : Std.Experimental::Format] (t0, t1, t2, t3, t4, t5, t6, t7, t8, t9, t10) : Std.Experimental::FormatArgs

impl [t0 : Std.Experimental::Format, t1 : Std.Experimental::Format, t2 : Std.Experimental::Format, t3 : Std.Experimental::Format, t4 : Std.Experimental::Format, t5 : Std.Experimental::Format, t6 : Std.Experimental::Format, t7 : Std.Experimental::Format, t8 : Std.Experimental::Format, t9 : Std.Experimental::Format, t10 : Std.Experimental::Format, t11 : Std.Experimental::Format] (t0, t1, t2, t3, t4, t5, t6, t7, t8, t9, t10, t11) : Std.Experimental::Format

impl [t0 : Std.Experimental::Format, t1 : Std.Experimental::Format, t2 : Std.Experimental::Format, t3 : Std.Experimental::Format, t4 : Std.Experimental::Format, t5 : Std.Experimental::Format, t6 : Std.Experimental::Format, t7 : Std.Experimental::Format, t8 : Std.Experimental::Format, t9 : Std.Experimental::Format, t10 : Std.Experimental::Format, t11 : Std.Experimental::Format] (t0, t1, t2, t3, t4, t5, t6, t7, t8, t9, t10, t11) : Std.Experimental::FormatArgs

impl [t0 : Std.Experimental::Format] (t0,) : Std.Experimental::Format

impl [t0 : Std.Experimental::Format] (t0,) : Std.Experimental::FormatArgs

impl [a : Std.Experimental::Format] Std.Experimental::Format::LeftAligned a : Std.Experimental::Format

impl [a : Std.Experimental::Format] Std.Experimental::Format::RightAligned a : Std.Experimental::Format

impl Std.Experimental::Format::WithPrecision Std::F32 : Std.Experimental::Format

impl Std.Experimental::Format::WithPrecision Std::F64 : Std.Experimental::Format

impl [a : Std.Experimental::Format] Std.Experimental::Format::WithSeparator a : Std.Experimental::Format

impl [a : Std.Experimental::Format] Std.Experimental::Slice a : Std.Experimental::Format

Writes a slice the same way as an array: [1, 2, 3].

impl [a : Std::Eq] Std.Experimental::Slice a : Std::Eq

Two slices are equal if they have equal elements in the same order.

impl [a : Std::ToString] Std.Experimental::Slice a : Std::ToString

Writes a slice the same way as an array: [1, 2, 3].

impl Std.Experimental::StringSlice : Std.Experimental::Format

Writes the text of the slice.

impl Std.Experimental::StringSlice : Std::Eq

Two string slices are equal if they have the same bytes.

impl Std.Experimental::StringSlice : Std::ToString

Returns the text of the slice as a string.

impl [a : Std.Experimental::Format] Std::Array a : Std.Experimental::Format

Writes the elements between [ and ], separated by ,, as to_string does.

impl Std::Bool : Std.Experimental::Format

Writes true or false, as to_string does.

impl Std::F32 : Std.Experimental::Format

Writes the shortest decimal text that reads back as the same number, as to_string does.

impl Std::F64 : Std.Experimental::Format

Writes the shortest decimal text that reads back as the same number, as to_string does.

impl Std::I16 : Std.Experimental::Format

impl Std::I32 : Std.Experimental::Format

impl Std::I64 : Std.Experimental::Format

impl Std::I8 : Std.Experimental::Format

impl [a : Std.Experimental::Format] Std::Option a : Std.Experimental::Format

Writes some(x) or none(), as to_string does.

impl Std::Ptr : Std.Experimental::Format

Writes sixteen hexadecimal digits, as to_string does.

impl [e : Std.Experimental::Format, a : Std.Experimental::Format] Std::Result e a : Std.Experimental::Format

Writes ok(x) or err(e), as to_string does.

impl Std::String : Std.Experimental::Format

impl Std::U16 : Std.Experimental::Format

impl Std::U32 : Std.Experimental::Format

impl Std::U64 : Std.Experimental::Format

impl Std::U8 : Std.Experimental::Format