thx libraries
You can run your thx code snippets with try.thx-lib.org

thx.core

Gitter

Build Status

Generic multi-purpose library. thx.core aims to be the lodash library for Haxe.

Data Structures

thx.core provides a few data types to complete the standard library.

AnonymousMap

Wraps an anonymous object in Map<String, T> compatible structure.

var map = new AnonymousMap({ name : "Franco" });

map.get("name"); // "Franco"

The intention of this class is not to encourage anonymous objects as data containers but to simplify the approach to untyped data like JSON results.

Either

Either is a value container. It can contain values from two different types but only one per instance. It can be handy when you want to manage values that can be in one of two possible states. A classic example is a Result where the wrapped value can be either a success or a failure.

typedef MyResult = Either<Error, String>;

var result : MyResult = Left(new Error("something smells"));

var result : MyResult = Right("the answer is 42");

Note that thx.Result is an abstract on top of Either with some additional features.

NOTE: Haxe v.3.2.0 introduces its own haxe.ds.Either type. It is 100% compatible with the one provided by thx. For that reason, thx adopts the official one when available. In the future thx.Either will probably be deprecated.

Nil

Nil is a special enum that only contains one constructor nil that takes no parameter. It denotes the absence of a value. It is very handy when you want to work on functions of arity 1 and you don't want to special case them to support an empty list of arguments.

function do<T>(arg : T) { /* do magic */ }

do(nil) { /* ... */ } // use `do` with an empty argument
typedef F<T> = T -> String;

// the following function satisfies the typedef above
function myF(_ : Nil) : String { /* ... */ }

Result

Result is a wrapper (abstract) on top of thx.Either. It semantically represents the result of an operation that can either a success or a failure.

var success : Result<String, String> = Right("victory!");

success.isSuccess; // true
success.isFailure; // false
success.value(); // "victory!"
success.error(); // null
success.optionValue(); // Some("victory!")
success.optionError(); // None

var failure : Result<String, String> = Left("oh, no ...");

failure.isSuccess; // false
failure.isFailure; // true
failure.value(); // null
failure.error(); // "oh, no ..."
failure.optionValue(); // None
failure.optionError(); // Some("oh, no ...")

thx.promise.Future always bring a result and thx.promise.Promise extend the concept by adding the possibility of a failure.

Set

A Set is a list of unique values. Values are unique in a way that no duplicates can exist in the same Set. Note that uniqueness is enforced by strict phisical equality. That means that is perfectly possible to have a Set of class instances where the instances contain exactly the same values but are referring different objects. Primitive values like Int, Float, String do not incur in such cases.

Set<T> is an abstract built on top of Array<T>. Like Array, it is a mutable structure and shares with it most of its methods with.

var set = Set.create();
set.add(1);
set.add(2);
set.add(3);
// again one!
set.add(1);

set.length == 3; // true!

A Set can be easily created from an Array:

var s : Set<Int> = [1,2,3,1]; // note that the repetead value will be removed

Set supports boolean operations like union, intersection and difference:

var s = ([1,2,3] : Set<Int>).union([2,3,4]).difference([2,3]);
// s contains [1,4]

Note that boolean operations return new Set instances and do not change the original instances.

Tuple

A Tuple is a value containing multiple values of potentially different types. All tuples are immutable; that means that any tuple operation that seems to change the Tuple it is creating a new structure instead.

A Tuple0 contains no value and it is equivalent to thx.Nil.nil.

A Tuple1 contains one value and it is a wrapper to the value type itself.

A Tuple2, the most conventional of the tuples, is an abstract wrapper around an object of type { _0 : T0, _1 : T1 }.

var t = new Tuple2("thx", 1);
t._0; // "thx", same as t.left
t._1; // 1, same as t.right

t.flip().left; // `flip` inverts the terms of the tuple and `left` is now 1

t.dropRight(); // return a Tuple1 which in this case results in "thx"

t.with("0.123") // appends a new value to the right creating a new Tuple3

Tuple3, Tuple4, Tuple5 and Tuple6 work much like Tuple but bring more values.

Type Helpers

thx.core also contains a lot of useful helper classes to simplify dealing with a lot of types from the standard library.

Most methods described below assume that the respective types have been required using using and are used as type extensions.

Arrays/Iterators/Iterables

Similarly to Lambda, Arrays/Iterators/Iterables provide extension methods to work with collections. They share most of the methods and are repeated to avoid useless casting or conversions and to provide optimizations where possible.

Some examples of the common features:

[1,2,3].all(function(i) return i > 1); // false
[1,2,3].any(function(i) return i > 1); // true

// filter works for any Iterator/Iterable like the normal Array.filter
[1,2,3].filter(Ints.isOdd); // [1,3]

[1,2,3].filter.fn(_ != 2); // equivalent to [1,2,3].filter(function(i) return i != 2)

[1,2,3].isEmpty(); // false

[1,2,3].map.fn(_ * 2); // [2,4,6]

Arrays

Beside the usual methods to traverse, reduce, slice and arrange arrays, Arrays contains peculiar things like:

In the thx.Arrays module are also defined a few specialized operations for specific type of arrays: ArrayFloats, ArrayInts and ArrayStrings. The numeric array variations provide methods for average, sum, min and max (plus compact for Float that removes non-finite numbers).

Iterators

it.isIterator() // checks that the instance has the right members to be an Iterator

Iterables

it.isIterable() // checks that the instance has the right members to be an Iterable

Floats

Floats contains extension methods to work with Float values. Some examples:

Functions

Extension methods for functions. Methods are roughly distributed between Functions, Functions0, Functions1, Functions2 and Functions3 where the number suffix denotes the arity (number of arguments) of the function that are going to be extended.

Ints

Extension methods for integer values. Many methods are implemented the same as in thx.Floats but specialized for Int values. Some are methods available in Std or Math but only available for Float.

Maps

Extension methods for Maps.

Objects

Extension methods for objects.

Options

Extension methods for the haxe.ds.Option type.

Nulls

Nulls provides extension methods that help to deal with nullable values.

var s : String = null;
trace(s.or('b')); // prints 'b'
s = 'a';
trace(s.or('b')); // prints 'a'

// or more complex
var o : { a : { b : { c : String }}} = null;
trace((o.a.b.c).or("B")); // prints 'B'
var o = { a : { b : { c : 'A' }}};
trace((o.a.b.c).or("B")); // prints 'A'

Note that the parenthesis wrap the entire chain of identifiers. That means that a null check will be performed for each identifier in the chain.

Identifiers can also be getters and methods (both are invoked only once and only if the check reaches them). Python seems to struggle with some native methods like methods on strings.

Strings

Extension methods for String. Some examples:

Strings also defines a type alias to StringTools. This way by including it, you also get all the StringTools extension methods:

using thx.Strings;

Dates

Extension methods for Date and Floats that represent date values.

Some examples:

Dates also defines a type alias to DateTools. This way by including it, you also get all the DateTools extension methods:

using thx.Dates;

Types

Extension methods to use on values, types and classes.

isAnonymousObject returns true if the passed argument is an anonymous object.

Types.isAnonymousObject({}); // true

valueTypeToString returns a string describing the type of any value.

Types.valueTypeToString("thx"); // "String"
Types.valueTypeToString(1); // "Int"
Types.valueTypeToString(Left("some")); // "thx.Either"

valueTypeInheritance returns an array of string describing the entire inheritance chain of the passed value.

valueTypeInheritance works on any value, not just class instances. Obviously most types will return an array of just one value.

class B extends A {};

Types.valueTypeInheritance(new B()); // ["B", "A"]

Dynamics.equals

Compares any two values checking their type first and recursively all their members for structural equality. It should work on any type. If the values passed are objects and they contain a method equals, it will be used to decide if the two objects match.

Dynamics.equals({ a : 1 }, { a : 1 }); // true
Dynamics.equals(1, 2); // false

ERegs.escape

It escapes any characer in a string that has a special meaning when used in a regular expression.

General Purpose Features

The following utilities have no direct relationship with standard types and just provides commonly required functionalities.

Timer

Timer provides several meaning to delay the execution of code. At the moment it is only implemented for platforms that have a native concept of Timer like Swf and JavaScript or c++/Neko with OpenFL or NME.

All of the Timer methods return a function with signature Void -> Void that can be used to cancel the timer.

// set the execution delayed by 200ms
var cancel = Timer.delay(doSomethingLater, 200);

// cancel immediately (`doSomethingLater` will never be executed)
cancel();

Note that calling the cancel function multiple times have no effect after the first execution.

Uuid

Helper class to generate UUID strings (version 4).

Uuid.create(); // generates something like f47ac10b-58cc-4372-a567-0e02b2c3d479

Errors

Haxe brings the power of being able to use any type to throw an exception. It is not uncommon to find code that simply does throw "my error. There is nothing wrong with that approach except that some times, most commonly in bigger applications that use many libraries, you need to be conservative when you want to catch an exception and introduce a catch(e : Dynamic) to be sure to not forget any possible error. The problem with Dynamic is that you don't really know how to access the error info. The type thx.Error described below tries to solve this problem providing a common and generic implementation.

Error

Represent a Runtime error or exception. When used with JS it inherits from the native Error type. It tries to bring information like error message and error location. Usage is super easy:

throw new Error('my error message');

Note that Error will try to collect (if possible) information about the error stack and the error location using haxe.PosInfos.

On top of thx.Error a few definitions are built for very common situations.

AbstractMethod

Mark a method as abstract. If it is not implemented by a sub-type a runtime exception is thrown indicating the class/method name that is abstract and has no implementation.

function myAbstract() {
    throw new AbstractMethod(); // no argument required
}

NotImplemented

Similarly to AbstracMethod it is used to mark method that have not been implementd yet.

function myNotImplemented() {
    throw new NotImplemented(); // no argument required
}

NullArgument

Checks that a certain argument of a function is not null and throws an exception otherwise.

function myMethod(value : String) {
    NullArgument.throwIfNull(value);
}

With arguments of type Array, String, Iterator or Iterable, it is also possible to check for emptyness:

function myMethod(value : String) {
    NullArgument.throwIfEmpty(value); // check that value is not `null` but also not empty ("")
}

Macro Helpers

Macros

Helper methods to use inside macro context.

MacroTypes

Several utility function to extract type information from macro types and expressions.

Install

From the command line just type:

haxelib install thx.core

To use the dev version do:

haxelib git thx.core https://github.com/fponticelli/thx.core.git