Crate lup [−] [src]

Lup ("loop")

A custom indexed loop macro library for Rust.

This library offers a different pattern than iterators based on indexed loops. Index loops are very common in game programming and scientific computing. The loops included in the library reflects the ones used in Dyon.

You can create your own custom loops by implementing the Lup trait.

Motivation

Closer to mathematical notation than the iterator pattern
Reduces chance of logical errors when solving complex problems
Supports continue, break or return from within the loop
Packed notation for nested loops, i in 0..3, j in 0..3 =>
Short-hand notation with safe range, i, j by list =>
Automatically infers evidence type of secrets
Can be used for numeric brute-force theorem proving
Ergononmic when working with vectors up to 4 dimensions

Usage

The loops Any, All, Max and Min uses the Secret structure. This type contains evidence that justifies the value.

Here is a simple example using the Any loop and the by syntax:

#[macro_use]
extern crate lup;

use lup::Any;

fn main() {
    let words = vec!["mary", "had", "a", "little", "lamb"];
    println!("Words:");
    println!("{:?}\n", words);

    // Find the word "lamb".
    let lamb = lup!(Any<_>: i by words => {words[i] == "lamb"});
    println!("Is there any word `lamb`?");
    println!("{}\n", lamb.value); // Prints `true`.

    println!("What is the evidence?");
    println!("{:?}\n", lamb.evidence); // Prints `Some(4)`.

    println!("Using the evidence to find the word:");
    println!("{}\n", words[lamb.evidence.unwrap()]); // Prints `lamb`.
}

The by syntax uses the range from the list. In the example above, this is the same as:

lup!(Any<_>: i in 0..words.len() => {words[i] == "lamb"})

Here is a slightly more complex example:

#[macro_use]
extern crate lup;

use lup::Any;

fn main() {
    // Create a 2D array.
    let arr = [[1, 2], [3, 4]];

    // Look for a number greater than 2.
    let b = lup!(Any<_>: i, j by arr => {arr[i][j] > 2});

    println!("{:?}", b.evidence); // Prints `Some((1, 0))`.

    // Get the number that is greater than 2.
    let ev = b.evidence.unwrap();
    println!("{}", arr[ev.0][ev.1]); // Prints `3`.
}

In the example above, there are two loops, one with index i and one with index j.

The type of the result of the inner j loop is Secret<(usize), bool>.

The type of the result of the outer i loop is Secret<(usize, usize), bool>.

The Secret type is used to combine results from loops to give meaningful answers.

Another example using the Max loop:

#[macro_use]
extern crate lup;

use lup::Max;

fn main() {
    let data = vec![
        (1, 1),
        (2, 2),
        (3, 4),
        (4, 4)
    ];

    let a = lup!(Max<_, _>: i by data => {data[i].0 as f32});
    let b = lup!(Max<_, _>: i by data => {data[i].1 as f32});

    println!("{} vs {}", a.value, b.value); // Prints `4 vs 4`.
    println!("{:?} vs {:?}", a.evidence, b.evidence); // Prints `Some(3) vs Some(2)`.
}

We convert to f32 since Max is implemented only for f32 and f64.

The evidence points to the item that first achieves maximum value.

Here is an example that demonstrates the full power of secrets:

#[macro_use]
extern crate lup;

use lup::{Any, Max};

fn main() {
    let data = vec![
        vec![1, 2, 6, 4, 5, 3],
        vec![4, 6, 9, 3, 2, 1],
    ];

    // Find out whether any list has a maximum value less than 7.
    let search = lup!(Any<_>: i by data => {
        lup!(Max<_, _>: j by data[i] => {data[i][j] as f32}).le(&7.0)
    });

    println!("{}", search.value); // Prints `true`.
    println!("{:?}", search.evidence); // Prints `Some((0, 2))`.
    let ev = search.evidence.unwrap();
    println!("{}", data[ev.0][ev.1]); // Prints `6`.
}

How do we know that a list has a maximum value less than 7? We know it because the maximum value of the first list is 6!

Secrets provide us with a meaningful reason why something is true.

In the example above, the secret of the Max loop propagates to the Any loop.

The example calls .le instead of using <= because Rust does not allow overriding the return value of comparison operators.

Macros

lup

Structs

All	For all loop.
Any	There exists loop.
For	Indexed for-loop.
Max	Maximum loop.
Min	Minimum loop.
Prod	Product loop.
Secret	Stores a secret.
Sift	A loop that creates a list.
Sum	Sum loop.
Vector	Vector construction loop.

Traits

Lup	Implemented by custom loops.