<?xml version="1.0"?>
<doc>
<assembly>
<name>Loyc.Essentials</name>
</assembly>
<members>
<member name="T:Loyc.Utilities.ConsoleMessageSink">
<summary>Sends all messages to the <see cref="M:System.Console.WriteLine"/>,
with hard-coded colors for Error, Warning, Note, Verbose, and Detail.</summary>
</member>
<member name="T:Loyc.Utilities.IMessageSink">
<summary>An interface for a class that accepts formatted messages.</summary>
<remarks>
IMessageSink is used for dependency injection of a target for formatted
messages; it could be used for log messages, compiler error messages, or
to report the progress of a process, for instance.
<para/>
Since .NET does not allow static members in an interface, the static
members can be found in <see cref="T:Loyc.Utilities.MessageSink"/>.
<para/>
Each message has a "type" <see cref="T:Loyc.Symbol"/> which indicates the
type of message being printed. For message sinks that are used as
loggers, this should be one of the following logging levels, listed
in order of importance: Fatal, Error, Warning, Note, Debug, Verbose.
For message sinks that are used for compiler messages, the standard
levels are: Fatal, Error, SoftError, Warning, Note, Detail. "SoftError"
is intended to describe code that is technically illegal, but which
does not impede code generation. "Detail" provides more information
about a previously-printed message, while "Note" is intended for
independent messages that are less severe than warnings.
<para/>
The message sink itself should perform localization, which can be done
with <see cref="M:Loyc.Localize.From(Loyc.Symbol,System.String,System.Object[])"/>.
<para/>
Only a single Write() method is truly needed (<see cref="!:Write(Symbol, string, params object[])"/>),
but efficiency reasons the interface contains two other writers. It
is expected to be fairly common that a message sink will drop some or
all messages without printing them, e.g. if a message sink is used for
logging, verbose messages might be "off" by default. It would be
wasteful to actually localize and format a message if the message will
not actually be printed, and it would also be wasteful to create an array
of objects to hold the arguments if they are just going to be discarded.
With that in mind, since most formatting requests only need a couple of
arguments, there is an overload of Write() that accepts up to two
arguments without the need to package them into an array, and there is
an overload that takes no formatting arguments (this indicates that
parameter substitution is not required and should not be attempted.)
<para/>
In addition, the caller can call <see cref="M:Loyc.Utilities.IMessageSink.IsEnabled(Loyc.Symbol)"/> to avoid
doing any work required to prepare a message for printing when a certain
category of output is disabled.
</remarks>
<seealso cref="T:Loyc.Utilities.MessageSink"/>
<seealso cref="T:Loyc.Utilities.ConsoleMessageSink"/>
<seealso cref="T:Loyc.Utilities.TraceMessageSink"/>
<seealso cref="T:Loyc.Utilities.NullMessageSink"/>
<seealso cref="T:Loyc.Utilities.MessageFilter"/>
<seealso cref="T:Loyc.Utilities.MessageHolder"/>
<seealso cref="T:Loyc.Utilities.MessageSplitter"/>
</member>
<member name="M:Loyc.Utilities.IMessageSink.IsEnabled(Loyc.Symbol)">
<summary>Returns true if messages of type 'type' will actually be
printed, or false if Write(type, ...) is a no-op.</summary>
</member>
<member name="M:Loyc.Utilities.ConsoleMessageSink.IsEnabled(Loyc.Symbol)">
<summary>Always returns true.</summary>
</member>
<member name="T:Loyc.Utilities.NullMessageSink">
<summary>Discards all messages.</summary>
</member>
<member name="M:Loyc.Utilities.NullMessageSink.IsEnabled(Loyc.Symbol)">
<summary>Always returns false.</summary>
</member>
<member name="T:Loyc.Utilities.TraceMessageSink">
<summary>Sends all messages to <see cref="M:System.Diagnostics.Trace.WriteLine(System.String)"/>.</summary>
</member>
<member name="M:Loyc.Utilities.TraceMessageSink.IsEnabled(Loyc.Symbol)">
<summary>Always returns true.</summary>
</member>
<member name="T:Loyc.Utilities.MessageHolder">
<summary>A message sink that stores all messages it receives.</summary>
</member>
<member name="M:Loyc.Utilities.MessageHolder.IsEnabled(Loyc.Symbol)">
<summary>Always returns true.</summary>
</member>
<member name="T:Loyc.Utilities.ILocationString">
<summary>An interface
</summary>
</member>
<member name="T:Loyc.Utilities.MessageFilter">
<summary>A decorator that uses a delegate to accept or ignore messages.</summary>
<remarks>The filter can accept or reject messages based on both the message
type and the actual message (format string). When someone calls
<see cref="M:Loyc.Utilities.MessageFilter.IsEnabled(Loyc.Symbol)"/>, the filter is invoked with only the type;
the message is set to null. Accepted messages are sent to the
<see cref="P:Loyc.Utilities.MessageFilter.Target"/> message sink.</remarks>
</member>
<member name="M:Loyc.Utilities.MessageFilter.IsEnabled(Loyc.Symbol)">
<summary>Returns true if <c>Filter(type, null)</c> and <c>target.IsEnabled(type)</c> are both true.</summary>
</member>
<member name="T:Loyc.Utilities.MessageSplitter">
<summary>A message sink that sends its messages to a list of other sinks.</summary>
</member>
<member name="M:Loyc.Utilities.MessageSplitter.IsEnabled(Loyc.Symbol)">
<summary>Returns true if <tt>s.IsEnabled(type)</tt> is true for at least one target message sink 's'.</summary>
</member>
<member name="T:Loyc.Utilities.GoInterface">
<summary>Mainly for internal use by the other GoInterface classes.</summary>
</member>
<member name="M:Loyc.Utilities.GoInterface.Unwrap(System.Object)">
<summary>Unwraps an object if it was wrapped by GoInterface. Unwrapping
is recursive, so that if a wrapper is inside another wrapper, the
underlying object is returned.</summary>
<param name="obj">Any object.</param>
<returns>Returns the original object wrapped by GoInterface. If the
specified object is not a GoInterface wrapper, returns obj itself.</returns>
</member>
<member name="M:Loyc.Utilities.GoInterface.UnwrapOnce(System.Object)">
<summary>Unwraps an object if it was wrapped by GoInterface. This
unwrapping is not recursive--if a wrapper is inside another wrapper,
only the outer wrapper is removed.</summary>
<param name="obj">Any object.</param>
<returns>Returns the original object wrapped by GoInterface. If the
specified object is not a GoInterface wrapper, returns obj itself.</returns>
</member>
<member name="T:Loyc.Utilities.IGoInterfaceWrapper">
<summary>All GoInterface wrappers implement this interface.</summary>
</member>
<member name="T:Loyc.Utilities.GoInterface`1">
<summary>GoInterface<Interface> creates wrappers around objects of your
choosing that implement the specified Interface, forwarding calls to
methods in the wrapped object. It is inspired by the duck-typed interfaces
in the Go programming language.</summary>
<remarks>
In the Go programming language, you do not say explicitly that your type
implements a given interface. Instead, a type is convertable to <i>any</i>
interface, just so long as it implements all the methods in the interface.
This often reminds people of "duck typing" in dynamic languages such as
Python or Ruby, but it is faster; in fact, Go interface calls are the same
speed as virtual method calls in C++ and C#!
<para/>
To put it in C# terms, if you have a class T...
<pre>public class T {
public void Foo(int x);
}</pre>
...and an interface called "Interface"...
<pre>public interface Interface {
void Foo(int x);
}</pre>
...then you can cast T to Interface even though T does not explicitly implement it.
<pre>Interface t = new T();</pre>
This cast can be implicit since the compiler can tell at compile time that
T implements the Interface. However, you can cast any object to Interface
and, at run-time, Go will determine whether it implements the Interface.
<para/>
I asked how Go dispatch works on the "Go Nuts" google group and was pointed
to two articles:
<para/>
http://research.swtch.com/2009/12/go-data-structures-interfaces.html
http://www.airs.com/blog/archives/281
<para/>
To summarize those, the first time you convert a type "T" to an interface
"Interface", a vtable (virtual function table) is generated just like the
kind used for virtual calls in .NET and C++. However, instead of storing
the vtable in the object itself like C++ and .NET do, Go stores the vtable
pointer alongside the interface pointer (i.e. an interface pointer is
really two pointers). This simple but unique design allows a single object
to implement an unlimited number of interfaces with overall performance
that is competitive with C# and Java.
<para/>
Unfortunately, as far as I can tell, there is no way to efficiently
implement this same technique in .NET without changing the CLR itself. A
virtual method table is just a list of pointers to functions; importantly,
function pointers in a virtual method table are not associated with a
specific object, which makes them different from .NET delegates. By not
associating the vtable with a specific object, it is possible to re-use the
same vtable with any number of objects (as long as they are of the same
class). However, .NET delegates are associated with specific objects, so we
can't use them to form a reusable vtable.
<para/>
Even if .NET allowed delegates that are not associated with a specific
object, delegate invocation on .NET is slower than virtual method
invocation; why this is so is not entirely clear to me, but part of the
reason may be that Microsoft decided to make delegates reference types when
they should have been a simpler 8-byte value type (just bundling a function
pointer with a 'this' pointer).
<para/>
However, just a few days ago I learned that Visual Basic 9 has a very
similar feature to Go called "dynamic interfaces", which pretty much lets
you do as described above (albeit only in Visual Basic). So far I've heard
nothing about how VB's dynamic interfaces work, but I got to thinking: how
hard would it be to bring go-style interfaces to all .NET languages, and
would it be possible to get good performance?
<para/>
The technique I chose doesn't have performance as good as you would get from
Go, but in exchange for a small performance hit (which I believe to be
unavoidable anyway), the GoInterface classes provide automatic interface
adaptations that you can't get in Go itself. Specifically, my GoInterface
classes can automatically do small type conversion tasks like enlarging
"int" to "long", boxing value types, and allowing return type covariance
(for instance, if the wrapped method returns a "string", the Interface can
return an "object".) And since GoInterface returns heap objects that
actually implement the interface you ask for (rather than, say, an 8-byte
structure imitating the Go implementation), it's very easy to use.
<para/>
The GoInterface classes use .NET Reflection.Emit to generate wrapper classes
in a "dynamic assembly"--basically a DLL that exists only in memory. Each
wrapper class implements a single interface of your choosing, and forwards
calls on that interface to an object of your choosing.
<para/>
Given the types from above...
<pre>public class T {
public void Foo(int x);
}
public interface Interface {
void Foo(int x);
}</pre>
...you can use GoInterface to cast T to Interface like this:
<pre>Interface t = GoInterface<Interface>.From(new T());</pre>
The first time you cast a T to Interface, GoInterface generates a wrapper
class such as the following on-the-fly:
<pre>public class T_46F3E18_46102A0 : Interface
{
T _obj;
public T_46F3E18_46102A0(T obj) { _obj = obj; }
void Foo(int x) { _obj.Foo(x); }
}</pre>
The hex numbers in the name of the type are simply handles to interface and
type being wrapped, in order to guarantee no name collisions occur when you
are wrapping a lot of different classes with GoInterface.
<para/>
After the first cast, all future casts are fairly fast, especially if you
call GoInterface<Interface,T>.From() instead of just
GoInterface<Interface>.From(). That's because after
GoInterface<Interface,T> is fully initialized, all its From() method does
is invoke a delegate that contains the following code:
<pre>delegate(T obj) { return new T_46F3E18_46102A0(obj); }</pre>
You can create wrappers with either GoInterface<Interface> or
GoInterface<Interface, T> (note the extra type argument "T").
<ul>
<li>GoInterface<Interface> is intended for creating wrappers when you do
not know the type of the object at compile time. For example, if you have a
list of objects of unknown type and you want to cast them to an interface,
use this one.</li>
<li>GoInterface<Interface, T> creates wrappers when you already know the
type of the object at compile time. This version assumes that T itself (and
not some derived class!) contains the methods you want to call.
GoInterface<Interface, T> has the disadvantage that it is unable to call
methods in a derived class of T. For example, you should not use
GoInterface<Interface, object> because the object class does not contain
a Foo method.</li>
</ul>
If you're not sure which one to use, use GoInterface<Interface>. If you
need to adapt a large number of objects to a single interface, you should
use GoInterface<Interface, T> where possible, because it is slightly
faster. GoInterface<Interface>, in contrast, has to examine each object
it is given to find out its most derived type. However, this process is
optimized so that an expensive analysis is only done once per derived type,
after which only a hashtable lookup is required.
<para/>
Compared to interfaces in the Go programming language, which have a 1-word
overhead for every interface pointer (the vtable pointer, which is 4 bytes
in 32-bit code), GoInterface wrappers normally have 3 words of overhead (2
words for the wrapper's object header and 1 word for a reference to the
wrapped object). Also, GoInterface wrapper classes are no doubt much more
costly to produce (since they involve run-time code generation), which will
increase your program's startup time and have a fixed memory overhead that
dwarfs Go's implementation. However, once you are up-and-running with
GoInterface wrappers, their performance should be pretty good. TODO:
benchmarks
<para/>
Note: GoInterface can create wrappers for value types (structures), not just
classes. Such wrappers have the same memory overhead as boxed structures,
which is one word less than wrappers for reference types.
<para/>
GoInterface wrappers automatically forward calls to object.ToString(),
object.GetHashCode() and object.Equals(), even though these methods are
not technically part of the interface being wrapped.
<para/>
GoInterface cannot wrap explicit interface implementations in the target
class. For instance, if the target class implements IEnumerable(of T), that
interface has two versions of the GetEnumerator function that differ only by
return type (one returns IEnumerator and the other returns IEnumerator(of
T)), so one of them must be implemented "explicitly". GoInterface will
typically only see the version that returns IEnumerator(of T), but this is
not a problem since IEnumerator(of T) is implicitly convertable to
IEnumerator, so GoInterface can use that one method to represent either of
them. In Visual Basic there is a caveat, since an explicit interface
implementation is allowed to be public. In that case, GoInterface will only
see the method's public name (not the name used in the interface).
</remarks>
</member>
<member name="T:Loyc.Utilities.CastOptions">
<summary>Options you can pass to GoInterface.From()</summary>
</member>
<member name="F:Loyc.Utilities.CastOptions.As">
<summary>If there is a mismatch, return null instead of throwing InvalidCastException</summary>
</member>
<member name="F:Loyc.Utilities.CastOptions.AllowUnmatchedMethods">
<summary>Allow the cast even if NumberOfUnmatchedMethods > 0</summary>
</member>
<member name="F:Loyc.Utilities.CastOptions.AllowRefMismatch">
<summary>Allow the cast even if NumberOfMethodsWithRefMismatch > 0</summary>
</member>
<member name="F:Loyc.Utilities.CastOptions.AllowMissingParams">
<summary>Allow the cast even if NumberOfMethodsMissingParameters > 0</summary>
</member>
<member name="F:Loyc.Utilities.CastOptions.NoUnwrap">
<summary>If the object to be wrapped is already wrapped,
GoInterface<Interface> will normally unwrap it before wrapping the
original object in another interface. Pass this flag to
GoInterface<Interface>.From() if you would like to make a wrapper
around another wrapper.
<para/>
Note 1: This flag only works in GoInterfaceFactory<Interface>,
not GoInterfaceFactory<Interface,T>.
Note 2: Unwrapping occurs recursively until an object is reached that
does not implement IGoInterfaceWrapper.
</summary>
</member>
<member name="T:Loyc.Utilities.GoInterfaceFactory`1">
<summary>For internal use. Base class of GoInterface<Interface,T>.Factory
and GoDirectCaster<Interface>.</summary>
</member>
<member name="T:Loyc.Utilities.GoDirectCaster`1">
<summary>Used by GoInterface<Interface> to cast objects directly to an
interface when it turns out that they implement that interface.</summary>
</member>
<member name="T:Loyc.Utilities.GoInterface`2">
<summary>GoInterface<Interface,T> creates a wrapper that implements
the specified Interface, forwarding calls to methods in T. It is inspired
by the duck-typed interfaces in the Go programming language.</summary>
<remarks>
Please see <see cref="T:Loyc.Utilities.GoInterface`1"/> for more information.
</remarks>
</member>
<member name="M:Loyc.Utilities.GoInterface`2.ForceFrom(`1)">
<summary>Creates a wrapper regardless of whether or not T could be
wrapped completely.</summary>
<exception cref="T:System.InvalidOperationException">The Interface is not
valid (e.g. it is not public or is not abstract)</exception>
<remarks>
GoInterface maps methods in certain cases where you might not
want it to--for example, if the Interface takes two ints and T only
takes one, GoInterface maps one to the other by omitting the second
parameter. To accept these mappings, call ForceFrom(T) or From(T,
CastOptions.AllowMissingParams | CastOptions.AllowRefMismatch); to
reject them, call From(T).
<para/>
ForceFrom always creates a wrapper, even if some methods of Interface
couldn't be matched with T at all. If you then call a method that
couldn't be wrapped, you'll get a MissingMethodException.
</remarks>
</member>
<member name="M:Loyc.Utilities.GoInterface`2.From(`1)">
<summary>Creates a wrapper if the interface matches T well.</summary>
<exception cref="T:System.InvalidCastException">T does not match the Interface
very well. Specifically, NumberOfUnmatchedMethods>0,
NumberOfMethodsMissingParameters>0 or NumberOfMethodsWithRefMismatch>0.</exception>
<returns>A pointer to a wrapper that implements the Interface.</returns>
</member>
<member name="M:Loyc.Utilities.GoInterface`2.From(`1,Loyc.Utilities.CastOptions)">
<summary>Creates a wrapper if T matches Interface according to the
specified CastOptions.</summary>
<returns>A pointer to a wrapper that implements the Interface.</returns>
<remarks>See CastOptions for more information.</remarks>
</member>
<member name="M:Loyc.Utilities.GoInterface`2.DefineCustomWrapperCreator(Loyc.Utilities.GoInterface{`0,`1}.GoWrapperCreator,Loyc.Utilities.GoInterface{`0,`1}.GoWrapperCreator)">
<summary>Defines a custom wrapper class for the type pair (Interface,
T). If you want to install a custom wrapper, you must do so before
From() or ForceFrom() is ever called on this pair of types, otherwise
an exception is thrown. Also, you cannot call this method twice on
the same pair of types.</summary>
<param name="from">A method to be invoked by From().</param>
<param name="forceFrom">A method to be invoked by ForceFrom().</param>
<remarks>
Since generating a wrapper is expensive and the wrapper cannot be
garbage-collected, I decided to make sure you don't waste time and
memory generating a wrapper you don't intend to use, by restricting
this method only to be used on type pairs that have never been used
before. Make sure you call this method as soon as possible, before
anybody calls From() or ForceFrom().
</remarks>
</member>
<member name="M:Loyc.Utilities.GoInterface`2.ContainsIdenticalMethod(System.Reflection.MethodInfo,System.Collections.Generic.List{Loyc.Utilities.GoInterface{`0,`1}.MethodAndParams})">
<summary>Returns true if 'otherMethods' contains a method identical to
'method' (IGNORING the return value!)</summary>
</member>
<member name="M:Loyc.Utilities.GoInterface`2.GenerateWrapperMethod(System.Reflection.Emit.TypeBuilder,System.Collections.Generic.List{Loyc.Utilities.GoInterface{`0,`1}.MethodAndParams},System.Int32,System.Collections.Generic.List{Loyc.Utilities.GoInterface{`0,`1}.MethodAndParams})">
<summary>Generates a method that implements baseMethod (a method of
Interface) and forwards the call to the same method on T.</summary>
<remarks>"Safe" parameter variance is allowed between Interface and T,
such as return type covariance.</remarks>
</member>
<member name="M:Loyc.Utilities.GoInterface`2.GetMatchingMethods(System.Reflection.MethodInfo,System.Collections.Generic.List{Loyc.Utilities.GoInterface{`0,`1}.MethodAndParams})">
<summary>Scans methods of T looking for a method matching a method
of Interface (baseMethod)</summary>
<remarks>
Before generating code for the method, we must find a matching
method of T. Note that we want to support various kinds of
"variance", including boxing if necessary:
<para/>
- Return type covariance. If T's method returns a derived class,
Interface's method can return a base class or interface. Also,
allow any return type if baseMethod returns void.
- "out" parameter covariance.
- T's "out" argument(s) can be absent from Interface, as long as
they are at the end of the argument list.
- Interface's input arguments can be absent from T, as long as the
missing parameters come at the end of the argument list.
- Input parameter contravariance. If T's method accepts a base class
(or interface) such as "object", Interface's method can accept a
derived class (or a class that implements said interface).
- If T takes a "ref" argument, allow the method in Interface not to
be "ref" and vice versa.
- T's method can be static
<para/>
Implicit conversion operators are not currently detected, except
primitive type conversions like Int16 to Float that C# allows you
to do implicitly. Information-losing conversions like Int64 to
Int32 are not supported.
<para/>
Variable argument lists are not supported specifically (they are
treated as arrays).
<para/>
Generic methods in T and Interface are not supported.
<para/>
Default (optional) arguments are generally supported.
<para/>
Argument names are ignored and need not match.
<para/>
Methods that differ only in case are not considered, but Aliases
specified with GoAliasAttribute are considered if a matching method
with the original name could not be found. All matching aliases are
considered together, as if they were overloads of each other.
<para/>
We scan all methods of "T" with a matching name and find the best
match, since there may be multiple methods matching these
requirements. For the most part I try to follow the rules of
the C# standard (ECMA-334 §14.4.2.1 and §14.4.2.2), but be a little
more liberal. The way I figure it, "void" should be treated like a
base class of "object". Note that this matching algorithm may reject
all overloads due to "ambiguity", in case one overload is not better
than all others.
</remarks>
</member>
<member name="M:Loyc.Utilities.GoInterface`2.ImplicitConvType(System.Type,System.Type)">
<summary>Figures out what kind of conversion you need to get from
"from" to "to", returning ConvType.IsA if no conversion is needed.</summary>
</member>
<member name="M:Loyc.Utilities.GoInterface`2.PrimSize(System.Type,System.Boolean@)">
<summary>Returns the size of a primitive integer or float type and
also tells you if the type is unsigned; note that IntPtr and
UIntPtr are not handled.</summary>
<returns>The size of type t, or 0 for unhandled types.</returns>
</member>
<member name="P:Loyc.Utilities.GoInterface`2.IsValidInterface">
<summary>If this value is false, Interface is not valid and ForceFrom
will throw InvalidOperationException if called. In that case, the other
values such as NumberOfUnmatchedMethods are zero, but have no meaning.</summary>
<remarks>Calling this property or any of the "int" properties forces
the wrapper class to be generated, during which the relationship
between Interface and T is analyzed.</remarks>
</member>
<member name="P:Loyc.Utilities.GoInterface`2.NumberOfUnmatchedMethods">
<summary>The number of methods in the interface for which a matching
method in T could not be found.</summary>
</member>
<member name="P:Loyc.Utilities.GoInterface`2.NumberOfAmbiguousMethods">
<summary>The number of methods in the interface for which a matching
method in T could not be found because T contained more than one
equally suitable match.</summary>
</member>
<member name="P:Loyc.Utilities.GoInterface`2.NumberOfMethodsMissingParameters">
<summary>The number of methods in the interface that were matched to
a method in T with one or more parameters dropped. For instance, if a
method in the interface takes two ints but T's method only takes one
int, the second int of </summary>
</member>
<member name="P:Loyc.Utilities.GoInterface`2.NumberOfMethodsWithRefMismatch">
<summary>The number of methods in the interface that were matched to a
method in T, in which there was a mismatch that one parameter was
passed by reference ("ref") and the other was passed by value.</summary>
</member>
<member name="T:Loyc.Utilities.GoInterface`2.Factory">
<summary>This helper class allows GoInterface<Interface> to cache
access to the static methods in GoInterface<Interface, T>, so that
it only needs to use reflection once.</summary>
</member>
<member name="T:Loyc.Utilities.GoInterface`2.MethodAndParams">
<summary>A MethodInfo with cached parameter information.</summary>
</member>
<member name="T:Loyc.Utilities.GoAliasAttribute">
<summary>This attribute is applied to a method of an interface to specify
alternate names that a method can have in T when you use GoInterface
<Interface, T> to produce a wrapper.</summary>
<example>
public class MyCollection
{
void Insert(object obj);
int Size { get; }
object GetAt(int i);
}
public interface ISimpleList
{
[GoAlias("Insert")] void Add(object item);
int Count
{
[GoAlias("get_Size")] get;
}
object this[int index]
{
[GoAlias("GetAt")] get;
}
}
void Example()
{
ISimpleList list = GoInterface<ISimpleList>.From(new MyCollection());
list.Add(10); // calls MyCollection.Insert(10)
}
</example>
</member>
<member name="T:Loyc.Utilities.GoDecoratorFieldAttribute">
<summary>
This attribute marks a field in an abstract class as pointing to a wrapped
object to which GoInterface should forward calls. It is used when you want
GoInterface to "complete" a decorator pattern for you.
</summary>
<remarks>
After writing the basic functionality of GoInterface, I realized it could
also serve as a handy way to implement the Decorator pattern. A decorator
is a class that wraps around some target class (usually sharing the same
interface or base class), while modifying the functionality of the target.
For instance, you could write a decorator for TextWriter that filters out
curse words, replacing them with asterisks.
<para/>
Writing decorators is sometimes inconvenient because you only want to
modify the behavior of some functions while leaving others alone.
Without GoInterface, you must write a wrapper for every method, manually
forwarding calls from the decorator to the target.
<para/>
GoInterface can help by generating forwarding functions automatically.
<para/>
The example shows how to use GoInterface to help you make a decorator.
</remarks>
<example>
// A view of an IList in which the order of the elements is reversed.
// The test suite offers this example in full; this partial implementation
// just explains the concepts.
public abstract class ReverseView<T> : IList<T>
{
// Use the GoDecoratorField attribute so that GoInterface will access
// the list through this field instead of creating a new field.
// Important: the field must be "protected" or "public" and have
// exactly the right data type; otherwise, GoInterface will ignore
// it and create its own field in the generated class.
[GoDecoratorField]
protected IList<T> _list;
// The derived class will init _list for you if you have a default
// constructor. If your constructor instead takes an IList argument,
// you are expected to initialize _list yourself.
protected ReverseView() { Debug.Assert(_list != null); }
// The downside of using GoInterface to help you make decorators is
// that GoInterface creates a derived class that overrides abstract
// methods in your own class, which means your class must be abstract,
// and users can't write "new ReverseView"--instead you must provide
// a static method like this one to create the wrapper.
public static ReverseView<T> From(IList<T> list)
{
return GoInterface<ReverseView<T>, IList<T>>.From(list);
}
// Here are two of several methods whose functionality we need to
// modify in order to reverse a list.
public int IndexOf(T item)
{
int i = _list.IndexOf(item);
return i == -1 ? -1 : Count - 1 - i;
}
public void Insert(int index, T item)
{
_list.Insert(Count - index, item);
}
// Here are the functions that we don't have to implement, which we
// allow GoInterface to implement automatically. Unfortunately, when
// implementing an interface you can't simply leave out the functions
// you want to remain abstract. C#, at least, requires you to make a
// list of the interface methods that you don't want to implement.
// This inconvenience is only when implementing an interface; if you
// are just deriving from an abstract base class, you don't have to
// do this because the base class already did it.
public abstract void Add(T item);
public abstract void Clear();
public abstract bool Contains(T item);
public abstract void CopyTo(T[] array, int arrayIndex);
public abstract int Count { get; }
public abstract bool IsReadOnly { get; }
public abstract bool Remove(T item);
public abstract IEnumerator<T> GetEnumerator();
// IEnumerable has two GetEnumerator functions so you must use an
// "explicit interface implementation" for the second one.
// You must write this one yourself, as it can't be marked abstract.
System.Collections.IEnumerator
System.Collections.IEnumerable.GetEnumerator()
{
return GetEnumerator();
}
}
</example>
</member>
<member name="T:Loyc.EzStopwatch">
<summary>
A wrapper around <see cref="T:System.Diagnostics.Stopwatch"/> with the convenient interface
similar to <see cref="T:Loyc.SimpleTimer"/>.
</summary>
<remarks>
EzStopwatch is a wrapper around the normal <see cref="T:System.Diagnostics.Stopwatch"/> that
is less clumsy to use: you can get the elapsed time and restart the
timer from zero with a single call to Restart(). The Stopwatch class
(prior to .NET 4, anyway) requires you to make three separate method
calls to do the same thing: you have to call ElapsedMilliseconds, then
Reset(), then Start().
<para/>
Unlike <see cref="T:Loyc.SimpleTimer"/>, this class does not start timing when
it is created, which allows it to be a struct without a constructor.
<para/>
EzStopwatch behaves differently from Stopwatch when restarting, because I
observed a problem using the timer to measure short time intervals. I ran
trials of three operations in a loop, and the loop was programmed to run
until the total elapsed time for one of the operations exceeded 100 ms. On
each iteration I restarted the timer three times because there were three
operations to measure, and when I replaced <see cref="T:Loyc.SimpleTimer"/> with
<see cref="T:Loyc.EzStopwatch"/> for greater accuracy, the loop ran forever! The
problem was that (depending on the benchmark's input parameters) the
operation could take less than 1 millisecond to complete, so
<see cref="P:Loyc.EzStopwatch.Millisec"/> always returned zero, and the total never reached
100.
<para/>
To solve this problem, when you "<see cref="M:Loyc.EzStopwatch.Restart"/>" the timer, it is
not completely reset to zero, but rather the current value of Millisec is
subtracted from the timer. This leaves a fractional amount of time less
than 1 millisecond in the timer, so that if you take two measurements
that each take 0.6 milliseconds, Millisec will return 0 the first time
and 1 the second time, leaving 0.2 milliseconds on the clock.
<para/>
TODO: change interfaces of SimpleTimer and EzStopwatch to better resemble
Stopwatch, even though the behavior of "Pause" and "Resume" is more obvious
than "Stop" and "Start".
</remarks>
</member>
<member name="M:Loyc.EzStopwatch.Restart">
<summary>Restarts the timer from zero (unpausing it if it is paused),
and returns the number of elapsed milliseconds prior to the reset.</summary>
</member>
<member name="M:Loyc.EzStopwatch.Reset">
<summary>Resets the timer to 0 and pauses it there.</summary>
</member>
<member name="M:Loyc.EzStopwatch.ClearAfter(System.Int32)">
<summary>Restarts the timer from zero if the specified number of
milliseconds have passed, and returns the former value of Millisec.</summary>
<returns>If the timer was restarted, this method returns the number of
elapsed milliseconds prior to the reset. Returns 0 if the timer was not
reset.</returns>
<remarks>If this method resets a paused timer, it remains paused but
Millisec is set to zero.</remarks>
</member>
<member name="P:Loyc.EzStopwatch.Millisec">
<summary>Gets or sets the current time on the clock.</summary>
<remarks>This property can be used whether the timer is running or not,
and it does not affect the value of <see cref="P:Loyc.EzStopwatch.Paused"/>. It is legal
to make the current value negative.</remarks>
</member>
<member name="T:Loyc.Math.Maths`1">
<summary>
This class helps generic code to perform calculations on numbers of
unknown type, by providing access to various math interfaces.
</summary>
<typeparam name="T">A numeric type.</typeparam>
<remarks>
If a certain math interface is not available for a certain type,
then the corresponding field will be null. For example,
Maths<int>.FloatMath is null because int is not floating-point.
The <see cref="F:Loyc.Math.Maths`1.Traits"/>, <see cref="F:Loyc.Math.Maths`1.Math"/>, and related properties
will be null for non-numeric types.
<para/>
TODO: support non-builtin types!
<para/>
Generic code that uses Maths<T> is slower than code that uses a
generic parameter with a math constraint. That's because generic
struct parameters are early-bound and can be inlined, while calls
through an interface such as IMath<T> are normal late-bound
interface calls and cannot be inlined. Compare the two examples
below.
</remarks>
<example>
// Calculates the length of a vector with magnitude (x, y):
// Slower version based on Maths<T>. Example: Length(3.0,4.0)
public T Length<T>(T x, T y)
{
var m = Maths<T>.Math;
return m.Sqrt(m.Add(m.Square(x), m.Square(y)));
}
// Calculates the length of a vector with magnitude (x, y):
// Faster version based on Maths<T>. Unfortunately, this version is
// inconvenient to call because the caller must specify which math
// provider to use. Example: Length<double,MathD>(3.0,4.0)
public T Length<T,M>(T x, T y) where M:struct,IMath<T>
{
var m = default(M);
return m.Sqrt(m.Add(m.Square(x), m.Square(y)));
}
</example>
</member>
<member name="T:Loyc.Collections.IBinumerator`1">
<summary>Extends the "enumerator" concept to allow backward enumeration.</summary>
<remarks>
When MoveNext() returns false, indicating that there are no more elements,
you can still call MovePrev() to go back to the previous element.
</remarks>
</member>
<member name="T:Loyc.Collections.IMEnumerator`1">
<summary>A mutable enumerator interface. Provides a "Remove" method like
Java iterators have, and allows you to modify the current item.</summary>
<remarks>Please note, not all collections will support "Remove".</remarks>
</member>
<member name="M:Loyc.Collections.IMEnumerator`1.Remove">
<summary>Removes the current item and moves to the next one. Remember
NOT to call MoveNext() immediately after Remove().</summary>
<returns>True if there is a next item after this one,
false if the removed item was the last one.</returns>
<exception cref="T:System.NotSupportedException">The collection does not permit
this operation.</exception>
</member>
<member name="P:Loyc.Collections.IMEnumerator`1.Current">
<summary>Gets or sets the value of the current item.</summary>
</member>
<member name="T:Loyc.Collections.IMBinumerator`1">
<summary>A mutable bidirectional enumerator interface. Please note that
the "Remove" method always moves to the next item, even though the
Binumerator is capable of moving backward.</summary>
</member>
<member name="M:Loyc.Collections.Range.Skip``2(``0@,System.Int32)">
<summary>Advances by the specified number of elements.</summary>
<param name="count">Number of items to remove from the beginning of the
range. If count is higher than the number of items in the range, no
exception is thrown but the return value will be less than this value.</param>
<returns>Returns the number of items skipped.</returns>
</member>
<member name="M:Loyc.Collections.Range.IntRange(System.Int32,System.Int32)">
<summary>Returns <c>new IntRange(start, count)</c>.</summary>
</member>
<member name="T:Loyc.Utilities.MessageSink">
<summary>Holds the <see cref="P:Loyc.Utilities.MessageSink.Current"/> default message sink for this
thread, <see cref="T:Loyc.Symbol"/>s for the common message types, such as
Warning and Error, and default instances of <see cref="T:Loyc.Utilities.ConsoleMessageSink"/>,
<see cref="T:Loyc.Utilities.TraceMessageSink"/> and <see cref="T:Loyc.Utilities.NullMessageSink"/>.</summary>
</member>
<member name="M:Loyc.Utilities.MessageSink.LocationString(System.Object)">
<summary>Returns <see cref="P:Loyc.Utilities.ILocationString.LocationString"/> if
'context' implements that interface, null if context is null, and
<see cref="M:System.Object.ToString"/> otherwise.</summary>
</member>
<member name="F:Loyc.Utilities.MessageSink.Trace">
<summary>Sends all messages to <see cref="M:System.Diagnostics.Trace.WriteLine(System.String)"/>.</summary>
</member>
<member name="F:Loyc.Utilities.MessageSink.Console">
<summary>Sends all messages to the <see cref="M:System.Console.WriteLine"/>.</summary>
</member>
<member name="F:Loyc.Utilities.MessageSink.Null">
<summary>Discards all messages.</summary>
</member>
<member name="P:Loyc.Math.ISizeReader`1.Width">
<summary>Gets the width of a rectangle (the difference between X coordinates).</summary>
</member>
<member name="P:Loyc.Math.ISizeReader`1.Height">
<summary>Gets the height of a rectangle (the difference between Y coordinates).</summary>
</member>
<member name="P:Loyc.Math.ISize3Reader`1.Depth">
<summary>Gets the depth of a rectangle (the difference between Z coordinates).</summary>
</member>
<member name="T:Loyc.Math.IRectangle3Reader`1">
<summary>Represents a read-only 3D rectangular prism.</summary>
<remarks>
The relationship between Z1, Z2 and Depth, as well as between the
other coodinates and Width/Height, depends on whether the object represents
a starting point plus a size, or a bounding rectangle or a pair of
points. Either the object stores a starting point (X1, Y1, Z1) and
a size (Width, Height, Depth), or it stores a starting point and an
ending point (X2, Y2, Z2).
<para/>
Conventionally, when using the size representation, the Width is
defined as X2 - X1, the Height as Y2 - Y1, and the Depth as Z2 - Z1.
A bounding rectangle is defined slightly differently: the Width is
X2 - X1 + e, the Height is Y2 - Y1 + e, and the Depth is Z2 - Z1 + e,
where e is an infitessimal value of type T (e=1 if T is an integer
type).
<para/>
Finally, this interface could simply represent a pair of points. In
that case, Width and Height return the absolute value of X2-X1 and
Y2-Y1 respectively.
<para/>
The object may or may not require X2 >= X1 and Y2 >= Y1 and Z2 >= Z1.
If X1>X2 or Y1>Y2 or Z1>Z2, the rectangle is said to be "not
normalized" and the <see cref="M:Loyc.Math.Rectangle3Ext.IsNormal``2(``0)"/> extension
method returns false.
</remarks>
</member>
<member name="T:Loyc.Math.IRectangleReader`1">
<summary>Represents a read-only 2D rectangle.</summary>
<remarks>
The relationship between X1, X2 and Width, and the relationship between
Y1, Y2 and Height, depends on whether the object represents a normal
(traditional Windows) rectangle, a bounding rectangle, or a pair of
points. A traditional rectangle defines its Height as Y2 - Y1, and its
Width as X2 - X1. A bounding rectangle is defined slightly differently:
the Width is X2 - X1 + e, and the Height is Y2 - Y1 + e, where e is an
infitessimal value of type T (e=1 if T is an integer type).
<para/>
Also, a traditional rectangle is stored as a starting point (X1, Y1)
and a size (Width, Height), while a bounding rectangle stores X2 and Y2
instead, not the Width and Height.
<para/>
Finally, this interface could simply represent a pair of points. In
that case, Width and Height return the absolute value of X2-X1 and
Y2-Y1 respectively.
<para/>
A rectangle may or may not require X2 >= X1 and Y2 >= Y1. If X1>X2 or
Y1>Y2, the rectangle is said to be "not normalized" and the
<see cref="M:Loyc.Math.RectangleExt.IsNormal``2(``0)"/> extension method returns false.
</remarks>
</member>
<member name="T:Loyc.Math.IRectangle3Base`1">
<summary>Represents a mutable 3D rectangular prism.</summary>
<typeparam name="T">Type of each coordinate.</typeparam>
<remarks>
This interface can represent one of three types of rectangles: either
"normal" rectangles with fundamental variables X, Y, Z, Width, Height,
Depth, bounding rectangles with two coordinate ranges (X1-X2), (Y1-Y2),
and (Z1-Z2), or pairs of points (X1, Y1, Z1) and (X2, Y2, Z2).
<para/>
Because of this fact, it is not clear when if modify X1 whether this
should affect X2 or Width. Similarly for Y1, Z1, X2, Y2 and Z2:
should the size property or the opposite boundary change?. To resolve
this question, this interface does not allow you to modify the
coordinates individually; instead you must change them in pairs: you
either set X and Width together, or X1 and X2 together; and similarly
for Y1/Y2/Height and Z1/Z2/Depth.
<para/>
You can also call the extension methods SetRect() or SetRange() to set
all six coordinates at once.
</remarks>
<seealso cref="!:IBoundingBox<T>"/>
</member>
<member name="T:Loyc.Math.IRectangleBase`1">
<summary>Represents a mutable 2D rectangle.</summary>
<typeparam name="T">Type of each coordinate.</typeparam>
<remarks>
This interface can represent one of three types of rectangles: either
"normal" rectangles with fundamental variables X, Y, Width, Height,
bounding rectangles with two coordinate ranges (X1-X2) and (Y1-Y2), or
or pairs of points (X1, Y1) and (X2, Y2).
<para/>
Because of this fact, it is not clear when you modify X1 whether this
should affect X2 or Width. Similarly, when you modify X2, Y1 or Y2, it
is not clear whether the size property or the opposite boundary should
change. To resolve this question, this interface does not allow you to
modify the coordinates individually; instead you must change them in
pairs: you either set X and Width together, or X1 and X2 together; and
similarly Y and Height together, or Y1 and Y2 together.
<para/>
You can also call the extension methods SetRect() or SetRange() to set
all four coordinates at once.
</remarks>
<seealso cref="!:IBoundingBox<T>"/>
</member>
<member name="T:Loyc.Math.IRectangle3`1">
<summary>Represents a mutable 3D rectangle.</summary>
<remarks>
This interface is separated into two bases,
<see cref="!:IRectangleBase3<T>"/> and <see cref="T:Loyc.Math.INewRectangle3`2"/>,
for the same reason that <see cref="T:Loyc.Math.IPoint`1"/>'s coordinates are
divided into <see cref="T:Loyc.Math.IPointBase`1"/> and <see cref="T:Loyc.Math.INewPoint`2"/>,
as explained in the documentation of <see cref="T:Loyc.Math.IPoint`1"/>.
</remarks>
</member>
<member name="T:Loyc.Math.Rectangle3Ext">
<summary>Contains methods to manipulate rectangles.</summary>
<remarks>Unfortunately, C# often can't infer the type parameters. Many of
these methods must be called with explicit type parameters.</remarks>
</member>
<!-- Badly formed XML comment ignored for member "T:Loyc.Collections.ValueCollection`2" -->
<!-- Badly formed XML comment ignored for member "T:System.Collections.Generic.IReadOnlyCollection`1" -->
<member name="T:Loyc.Collections.SelectNegListSources`1">
<summary>
Provides view of an <see cref="T:Loyc.Collections.IListSource`1"/> in which element [i] is a
<see cref="T:Loyc.Collections.NegListSource`1"/> N such that N[0] refers to element [i] in the
original list. See <see cref="M:Loyc.Collections.LCExt.NegLists``1(Loyc.Collections.IListSource{``0})"/> for more
information.
</summary>
<seealso cref="T:Loyc.Collections.SelectNegLists`1"/>
</member>
<member name="T:Loyc.Collections.ListSourceBase`1">
<summary>Helps you implement sources (read-only collections) by providing
default implementations for most methods of IList(T) and
IListSource(T).</summary>
<remarks>
You only need to implement two methods yourself:
<code>
public abstract int Count { get; }
public abstract T TryGet(int index, ref bool fail);
</code>
</remarks>
</member>
<member name="T:Loyc.Collections.SourceBase`1">
<summary>Helps you implement sources (read-only collections) by providing
default implementations for most methods of <see cref="T:System.Collections.Generic.ICollection`1"/> and
<see cref="T:System.Collections.Generic.IReadOnlyCollection`1"/>.</summary>
<remarks>
You only need to implement two methods yourself:
<code>
public abstract int Count { get; }
public abstract Iterator<T> GetIterator();
</code>
</remarks>
</member>
<member name="T:Loyc.Collections.IListSource`1">
<summary>A read-only list indexed by an integer.</summary>
<remarks>
The .NET collection classes have a very simple and coarse interface.
<para/>
Member list:
<code>
public T this[int index] { get; }
public T TryGet(int index, ref bool fail);
public Iterator<T> GetIterator();
public int Count { get; }
public IEnumerator<T> GetEnumerator();
System.Collections.IEnumerator System.Collections.IEnumerable.GetEnumerator();
</code>
The term "source" means a read-only collection, as opposed to a "sink" which
is a write-only collection. The purpose of IListSource is to make it easier
to implement a read-only list, by lifting IList's requirement to write
implementations for Add(), Remove(), etc. A secondary purpose is, of course,
to guarantee users don't mistakenly call those methods on a read-only
collection.
<para/>
I have often wanted to access the "next" or "previous" item in a list, e.g.
during parsing, but it inconvenient if you have to worry about whether the
the current item is the first or last. In that case you must check whether
the array index is valid, which is both inconvenient and wasteful, because
the list class will check the array index again, and then the .NET runtime
will check the index a third time when reading the internal array. To make
this more efficient, IListSource has a TryGet() method that does not throw
on failure, but returns default(T).
<para/>
As IListSource is supposed to be a simpler alternative to IList, I didn't
want to require implementers to implement more than two indexers. There are
two additional TryGet extension methods, though:
<code>
bool TryGet(int index, ref T value);
T TryGet(int, T defaultValue);
</code>
If T is defined as "out" (covariant) in C# 4, these methods are not allowed
in IListSource anyway and MUST be extension methods.
<para/>
Note that "value" is a "ref" rather than an "out" parameter, unlike
Microsoft's own TryGetValue() implementations. Using ref parameter allows
the caller to choose his own default value in case TryGet() returns false.
<para/>
Using <see cref="T:Loyc.Collections.ListSourceBase`1"/> as your base class can help you
implement this interface faster.
</remarks>
</member>
<!-- Badly formed XML comment ignored for member "T:System.Collections.Generic.IReadOnlyList`1" -->
<member name="P:System.Collections.Generic.IReadOnlyList`1.Item(System.Int32)">
<summary>Gets the item at the specified index.</summary>
<exception cref="T:System.ArgumentOutOfRangeException">The index was not valid
in this list.</exception>
<param name="index">An index in the range 0 to Count-1.</param>
<returns>The element at the specified index.</returns>
</member>
<member name="M:Loyc.Collections.IListSource`1.TryGet(System.Int32,System.Boolean@)">
<summary>Gets the item at the specified index, and does not throw an
exception on failure.</summary>
<param name="index">An index in the range 0 to Count-1.</param>
<param name="fail">A flag that is set on failure. To improve
performance slightly, this flag is not necessarily cleared on
success.</param>
<returns>The element at the specified index, or default(T) if the index
is not valid.</returns>
<remarks>In my original design, the caller could provide a value to
return on failure, but this would not allow T to be marked as "out" in
C# 4. For the same reason, we cannot have a ref/out T parameter.
Instead, the following extension methods are provided:
<code>
bool TryGet(int index, ref T value);
T TryGet(int, T defaultValue);
</code>
</remarks>
</member>
<member name="M:Loyc.Collections.IListSource`1.Slice(System.Int32,System.Int32)">
<summary>Returns a sub-range of this list.</summary>
<param name="start">The new range will start at this index in the current
list (this location will be index [0] in the new range).</param>
<param name="count">The desired number of elements in the new range,
or int.MaxValue to get all elements until the end of the list.</param>
<returns>Returns a sub-range of this range.</returns>
<exception cref="T:System.ArgumentException">The start index was below zero.</exception>
<remarks>The (start, count) range is allowed to be invalid, as long
as start is zero or above.
<ul>
<li>If count is below zero, or if start is above the original Count, the
Count of the new slice is set to zero.</li>
<li>if (start + count) is above the original Count, the Count of the new
slice is reduced to <c>this.Count - start</c>. Implementation note:
do not compute (start + count) because it may overflow. Instead, test
whether (count > this.Count - start).</li>
</ul>
Most collections should use the following implementation:
<pre>
IRange<T> IListSource<T>.Slice(int start, int count) { return Slice(start, count); }
public Slice_<T> Slice(int start, int count) { return new Slice_<T>(this, start, count); }
</pre>
</remarks>
</member>
<!-- Badly formed XML comment ignored for member "T:Loyc.Collections.ListExt" -->
<member name="M:Loyc.Collections.ListExt.Sort``1(System.Collections.Generic.IList{``0})">
<inheritdoc cref="!:Sort(IList<T>, int, int, Comparison<T>)"/>
</member>
<member name="M:Loyc.Collections.ListExt.Sort``1(System.Collections.Generic.IList{``0},System.Comparison{``0})">
<inheritdoc cref="!:Sort(IList<T>, int, int, Comparison<T>)"/>
</member>
<member name="M:Loyc.Collections.ListExt.Sort``1(System.Collections.Generic.IList{``0},System.Int32,System.Int32,System.Comparison{``0})">
<summary>Performs a quicksort using a Comparison function.</summary>
<param name="index">Index at which to begin sorting a portion of the list.</param>
<param name="count">Number of items to sort starting at 'index'.</param>
<remarks>
This method exists because the .NET framework offers no method to
sort <see cref="T:System.Collections.Generic.IList`1"/>--you can sort arrays and <see cref="T:System.Collections.Generic.List`1"/>,
but not IList.
</remarks>
</member>
<member name="M:Loyc.Collections.ListExt.StableSort``1(System.Collections.Generic.IList{``0},System.Comparison{``0})">
<summary>Performs a stable sort, i.e. a sort that preserves the
relative order of items that compare equal.</summary>
<remarks>
This algorithm uses a quicksort and therefore runs in O(N log N) time,
but it requires O(N) temporary space (specifically, an array of N
integers) and is slower than a standard quicksort, so you should use
it only if you need a stable sort.
</remarks>
</member>
<member name="M:Loyc.Collections.ListExt.InsertionSort``1(System.Collections.Generic.IList{``0},System.Int32,System.Int32,System.Comparison{``0})">
<summary>Performs an insertion sort.</summary>
<remarks>The insertion sort is a stable sort algorithm that is slow in
general (O(N^2)). It should be used only when (a) the list to be sorted
is short (less than 10-20 elements) or (b) the list is very nearly
sorted already.</remarks>
<seealso cref="M:Loyc.Collections.Impl.InternalList.InsertionSort``1(``0[],System.Int32,System.Int32,System.Comparison{``0})"/>
</member>
<member name="M:Loyc.Collections.ListExt.SortPair``1(System.Collections.Generic.IList{``0},System.Int32,System.Int32,System.Comparison{``0})">
<summary>Sorts two items to ensure that list[i] is less than list[j].</summary>
<returns>True if the array elements were swapped, false if not.</returns>
</member>
<member name="M:Loyc.Collections.ListExt.Swap``1(System.Collections.Generic.IList{``0},System.Int32,System.Int32)">
<summary>Swaps list[i] with list[j].</summary>
</member>
<member name="M:Loyc.Collections.ListExt.IndexWhere``1(System.Collections.Generic.IList{``0},System.Func{``0,System.Boolean})">
<summary>Gets the lowest index at which a condition is true, or -1 if nowhere.</summary>
</member>
<member name="M:Loyc.Collections.ListExt.LastIndexWhere``1(System.Collections.Generic.IList{``0},System.Func{``0,System.Boolean})">
<summary>Gets the highest index at which a condition is true, or -1 if nowhere.</summary>
</member>
<member name="M:Loyc.Collections.ListExt.Randomized``1(System.Collections.Generic.IList{``0})">
<summary>Quickly makes a copy of a list, as an array, in random order.</summary>
</member>
<member name="M:Loyc.Collections.ListExt.SelectArray``2(``0[],System.Func{``0,``1})">
<summary>Maps an array to another array of the same length.</summary>
</member>
<member name="M:Loyc.Collections.ListExt.RemoveAll``1(System.Collections.Generic.IList{``0},System.Predicate{``0})">
<summary>Removes the all the elements that match the conditions defined by the specified predicate.</summary>
<returns>The number of elements removed from the list</returns>
</member>
<!-- Badly formed XML comment ignored for member "T:Loyc.Collections.CollectionDebugView`1" -->
<member name="T:Loyc.Collections.DictionaryDebugView`2">
<summary>Workaround for a limitation of the debugger: it doesn't support
<see cref="T:Loyc.Collections.CollectionDebugView`1"/> when T is <see cref="T:System.Collections.Generic.KeyValuePair`2"/>.
This class is identical, except that T is replaced with KeyValuePair{K,V}.
</summary>
</member>
<!-- Badly formed XML comment ignored for member "T:Loyc.Collections.ListSourceDebugView`1" -->
<member name="T:Loyc.SimpleTimer">
<summary>
A fast, simple timer class with a more convenient interface than
System.Diagnostics.Stopwatch. Its resolution is typically 10 ms.
</summary>
<remarks>
With SimpleTimer, the timer starts when you construct the object and
it is always counting. You can get the elapsed time and restart the
timer from zero with a single call to Restart(). The Stopwatch class
requires you to make three separate method calls to do the same thing:
you have to call ElapsedMilliseconds, then Reset(), then Start().
</remarks>
</member>
<member name="M:Loyc.SimpleTimer.Restart">
<summary>Restarts the timer from zero (unpausing it if it is paused),
and returns the number of elapsed milliseconds prior to the reset.</summary>
</member>
<member name="M:Loyc.SimpleTimer.ClearAfter(System.Int32)">
<summary>Restarts the timer from zero if the specified number of
milliseconds have passed, and returns the former value of Millisec.</summary>
<returns>If the timer was restarted, this method returns the number of
elapsed milliseconds prior to the reset. Returns 0 if the timer was not
reset.</returns>
<remarks>If this method resets a paused timer, it remains paused but
Millisec is set to zero.</remarks>
</member>
<member name="P:Loyc.SimpleTimer.Millisec">
<summary>
The getter returns the number of milliseconds since the timer was
started; the resolution of this property depends on the system timer.
The setter changes the value of the timer.
</summary>
</member>
<member name="T:Loyc.Math.IPoint`1">
<summary>A mutable 2D point with X and Y coordinates.</summary>
<remarks>
WARNING: When casting a point (or vector) structure to this interface,
it is boxed, making a copy. Changes made through a reference to IPoint do
not affect the original point!
<para/>
It is important to distinguish between generic code that operates on points
(e.g. Foo<Point,T>(Point x) where Point:IPoint<T>) and code that uses
the IPoint interface directly (e.g. Foo(IPoint<int>) or even
Foo<T>(IPoint<T> x)). The latter uses slow, late-bound interface
calls and the boxing-copy issue mentioned before must be kept in mind.
Generic code that uses IPoint as a <i>constraint</i>, not as a <i>parameter
type,</i> is faster and does not have the same problem because it does not
actually box the point, nor does it use late-bound invocation.
<para/>
Normally this interface is not used directly, and the only operation
provided is New(). It is provided in case you want it, but generally
it's better to use <see cref="T:Loyc.Math.Point`1"/>.
<para/>
In order for this interface to work more easily in generic code, there is
no corresponding IVector type for vectors because generic code must declare
every type it needs as a separate type parameter, which makes the code very
cumbersome to write already, even without a point/vector distinction.
<para/>
The New() method is not normally used in generic code because it returns
IPoint<T>, not the original point type. It is provided mainly in case
somebody wants to use the raw interface to manipulate points.
<para/>
Due to a limitation of C#, the X and Y coordinates are separated into a
separate interface (<see cref="T:Loyc.Math.IPointBase`1"/>) from the New() method in
<see cref="T:Loyc.Math.INewPoint`2"/>. Without this separation, it's impossible
to write fast generic code that can operate on both IPoint itself and on
concrete types such as <see cref="T:Loyc.Math.Point`1"/>. The reason for this is very
subtle. To understand it, consider the following generic method that adds
two points together:
<para/>
<code>
public static Point Add<Point,T,M>(this M m, Point a, Point b)
where Point : IPoint<T>
where M : IAdditionGroup<T>
{
return a.New(m.Add(a.X, b.X), m.Add(a.Y, b.Y));
}
</code>
As written, this code does not compile. The reason is that a.New() does not
return a Point; instead, it returns <see cref="T:Loyc.Math.IPoint`1"/>, which is a more
general (interface) type than Point (which is probably a struct). Therefore,
in order for the code above to work, a cast from IPoint to Point would be
necessary. However, the boxing performed by new() and the unboxing performed
by the cast will slow down the method. My goal, however, is to allow generic
code to run fast; otherwise it's hard to justify the extra effort required
to make the code generic. After all, the code to add non-generic points is
trivial in comparison:
<code>
public static PointD Add(PointD a, PointD b) { return a + b; }
</code>
You might think to yourself, "okay, why don't we just add a new()
constraint on Point?" In that case the Add() method can be written as
follows:
<code>
public static Point Add<Point,T,M>(this M m, Point a, Point b)
where Point : IPoint<T>, new()
where M : IAdditionGroup<T>
{
Point p = new Point();
p.X = m.Add(a.X, b.X);
p.Y = m.Add(a.Y, b.Y);
return p;
}
</code>
This works if the input is a concrete point type, but this version of the
method cannot be used if Point happens to be <see cref="T:Loyc.Math.IPoint`1"/> itself;
you cannot do "new IPoint" because it is an interface. To solve this I
considered splitting out New() into a separate interface and using it as a
constraint of the generic method:
<code>
public static Point Add<Point,T,M>(this M m, Point a, Point b)
where Point : IPoint<T>, INewPoint<Point, T>
where M : IAdditionGroup<T>
{
return a.New(m.Add(a.X, b.X), m.Add(a.Y, b.Y));
}
</code>
This code compiles under one condition: IPoint must <i>not</i> be derived
from INewPoint<IPoint<T>,T>. Because if it is, then the call to New()
is ambiguous: does a.New() refer to INewPoint<IPoint<T>,T>.New() or
to INewPoint<Point,T>.New()? Remember, IPoint is not the same as Point
from the compiler's perspective--IPoint is an interface, but Point is
typically a struct (it could be the same as IPoint, but in general, it is
not). The compiler doesn't know which version of New() to call, so it
refuses to compile the code. It will compile if we change the method body
to
<code>
return ((INewPoint<Point,T>)a).New(m.Add(a.X, b.X), m.Add(a.Y, b.Y));
</code>
The cast resolves the ambiguity, but as a side-effect, 'a' is boxed and
the call to New() becomes a virtual call that cannot be inlined. So the
same performance penalty is back!
<para/>
But as I was saying, the original code does compile if IPoint is <i>not</i>
derived from INewPoint. Unfortunately, if IPoint is not derived from
INewPoint then it is impossible to pass a reference to IPoint to this
method (because it no longer meets the constraints). Remember, that is
the limitation I am trying to avoid!
<para/>
One more "solution" is not to create any new points:
<code>
public static Point Add<Point,T,M>(this M m, Point a, Point b)
where Point : IPoint<T>
where M : IAdditionGroup<T>
{
a.X = m.Add(a.X, b.X);
a.Y = m.Add(a.Y, b.Y);
return a;
}
</code>
Alas, this version of the code modifies the point 'a' if Point is IPoint,
but it does not modify 'a' if Point is a struct, because structs are passed
by value. This inconsistency is not acceptable, and besides, there are
(of course) situations where creating new points is required.
<para/>
The problem is that if there is only one New() method defined (in the
point structures such as PointI and PointD) then it's impossible to pass
references to IPoint to Add(); however, if there are two New() methods (one
in the point struct and one in IPoint), it is impossible to tell the C#
compiler which method we want to call without slowing down the code as a
side-effect. My solution to this very peculiar problem is to split IPoint
into two independent interfaces, IPointBase and INewPoint. This separation
allows us to tell the C# compiler that Point implements only one of the
New() methods, not both:
<code>
public static Point Add<Point,T,M>(this M m, Point a, Point b)
where Point : IPointBase<T>, INewPoint<Point, T>
where M : IAdditionGroup<T>
{
return a.New(m.Add(a.X, b.X), m.Add(a.Y, b.Y));
}
</code>
IPointBase, unlike IPoint, does not have a New() method, so only the
New() method in INewPoint<Point, T> is available to be called, and the
C# compiler stops complaining. Also, since IPoint<T> implements both
IPointBase<T> and INewPoint<IPoint<T>, T>, it meets the generic
constraints of this method and can be passed to it.
<para/>
Note that you don't have to write methods like Add() yourself (they are
provided as extension methods on IPoint.) Still, if you've read this far,
you're probably now afraid of the effort required to write generic code!
Your fear may be justified. But there is another, easier way that you can
write generic code, based on <see cref="T:Loyc.Math.Point`1"/> instead of IPoint:
<code>
public static Point<T> Add<T>(Point<T> a, Point<T> b)
{
return a+b;
}
</code>
A lot easier without all those constraints, yes? The main disadvantage of
this version is that it doesn't have great performance, because the
additions are done through interface calls. A second disadvantage is that
you can't pass an IPoint to it. That's okay because as stated before,
normally the IPoint interface is not used directly!
<para/>
Code that uses Point<T,M> can run faster:
<code>
public static Point<T,M> Add<T,M>(Point<T,M> a, Point<T,M> b)
{
return a+b;
}
</code>
So, in summary, supporting fast generic code that can also operate on IPoint
requires this odd arrangement of interfaces, and if you want to write such
generic code then you will need three type parameters (Point, T and M) with
the following constraints:
<code>
where Point : IPointBase<T>, INewPoint<Point, T>
where M : IMath<T> // or another math interface
</code>
It may help to place your methods in a generic class (of Point, T and M) so
that you only have to write the constraints once.
</remarks>
</member>
<member name="T:Loyc.Math.IPointBase`1">
<summary>This interface exists to work around a limitation of C#; use
<see cref="T:Loyc.Math.IPoint`1"/> instead.</summary>
<remarks>
C# cannot combine a getter property and a setter property from two
interfaces, so this interface cannot inherit its getters from <see cref="T:Loyc.Math.IPointReader`1"/>. The workaround is to define another getter in
the read-write interface for each getter in the read-only interface. As far
as the CLR is concerned, the two getters are unrelated, but you won't
notice that unless you need to explicitly implement this interface.
</remarks>
</member>
<member name="P:Loyc.Math.IPointBase`1.X">
<summary>Horizontal coordinate of a point or vector.</summary>
<remarks>In geographic points, X represents the longitude.</remarks>
</member>
<member name="P:Loyc.Math.IPointBase`1.Y">
<summary>Vertical coordinate of a point or vector.</summary>
<remarks>
In 3D spaces, Y is sometimes used as a depth coordinate instead.
In geographic points, Y represents the latitude.
</remarks>
</member>
<member name="T:Loyc.Math.INewPoint`2">
<summary>This interface exists to work around a limitation of C#; see
<see cref="T:Loyc.Math.IPoint`1"/>.</summary>
</member>
<member name="M:Loyc.Math.Vector`1.op_Multiply(Loyc.Math.Vector{`0},Loyc.Math.Vector{`0})">
<summary>Dot product. a*b equals lhs.Length*rhs.Length*Cos(theta) if theta
is the angle between two vectors.</summary>
</member>
<member name="M:Loyc.Math.Vector`1.Cross(Loyc.Math.Vector{`0})">
<summary>Computes the "cross product" of a pair of vectors.</summary>
<remarks>
This is not a general cross product, as cross product is only a 3D concept,
but this operator acts as though the two points were in the Z=0 plane and
returns the Z coordinate of the cross product: b.X * a.Y - b.Y * a.X.
This value is zero if the vectors are parallel; it is a.Length * b.Length
or -a.Length * b.Length if the vectors are perpendicular. One use of
cross product is to determine whether the angle between two lines is greater
or less than 180 degrees, corresponding to return values less or greater than
zero.
</remarks>
</member>
<member name="M:Loyc.Math.Vector`1.Rot90">
<summary>Rotates a vector 90 degrees.</summary>
<remarks>
Rotatation is clockwise if increasing Y goes downward, counter-
clockwise if increasing Y goes upward. If the vector represents the
direction of a line, the result also represents the coefficients
(a,b) of the implicit line equation aX + bY + c = 0.
</remarks>
</member>
<member name="M:Loyc.Math.Vector`1.op_UnaryNegation(Loyc.Math.Vector{`0})">
<summary>Reverses a vector.</summary>
</member>
<member name="P:Loyc.Math.Vector`1.Quadrance">
<summary>Gets the square of the length of the vector.</summary>
</member>
<member name="P:Loyc.Math.Vector`1.Length">
<summary>Gets the length of the vector.</summary>
</member>
<member name="P:Loyc.Math.Vector`1.Angle">
<summary>Gets the angle from 0 to 2*PI of the vector, where (1,0) has
angle 0 and (0,1) has angle PI/2.</summary>
</member>
<member name="T:Loyc.Math.IAdditionGroup`1">
<summary>
This defines a Group with the operation +, the neutral element Zero,
and an operation - that is defined in terms of the inverse. A Negate
operation is not provided so that this interface makes more sense for
use with unsigned types.
Axioms that have to be satisified by the operations:
Commutativity of addition: Add(a,b)=Add(b,a) for all a,b in T
Associativity of addition: Add(Add(a,b),c)=Add(a,Add(b,c))
Inverse of addition: Add(a,Negate(a))==Zero
Subtraction: Subtract(a,b)==Add(a,Negate(b))
Neutral element: Add(Zero,a)==a for all a in T
</summary>
</member>
<member name="P:Loyc.Math.IZeroProvider`1.Zero">
<summary>Returns the "zero" or additive identity of this type.</summary>
</member>
<member name="T:Loyc.UString">
<summary>UString is a wrapper around string that provides a range of 21-bit
UCS-4 characters. "U" stands for "Unicode", as in UCS-4, as opposed to a
normal string that is UTF-16.</summary>
<remarks>
It has been suggested that Java and .NET's reliance on 16-bit "unicode"
characters was a mistake, because it turned out that 16 bits was not enough
to represent all the world's characters. And I agree.
<para/>
Instead it has been suggested that we should use <a href="http://www.utf8everywhere.org/">
UTF-8 everywhere</a>. To scan UTF-8 data instead of UTF-16 while still
supporting non-English characters (or "ĉĥáràĉtérŝ", as I like to say),
it is useful to have a bidirectional iterator that scans characters one
codepoint at a time. UString provides that functionality for .NET, and
the nice thing about UString is that it's portable to UTF-8 environments.
That is, by using UString, your code is portable to a UTF-8 environment
that uses an equivalent implementation of UString for UTF-8. Eventually
I want Loyc to target native environments, where UTF-8 is common, and
UString can provide a common data type for both UTF-8 and UTF-16
environments.
<para/>
UString is a bidirectional range of "uchar", which is an alias for int
(uchar means "Unicode" or "UCS-4", rather than "unsigned").
<para/>
The difference between StringSlice and UString is that StringSlice is a
random-access range of char, while UString is a bidirectional range of
uchar (int). Since UString implements <see cref="!:IListSource<char>"/>,
it requires StringSlice in order to support the Slice method.
<para/>
UString has a <see cref="M:Loyc.UString.DecodeAt(System.Int32)"/> method that tries to decode
a UTF character to UCS at a particular index.
<para/>
Since UString and StringSlice are just slightly different views of the
same data, you can implicitly cast between them.
<para/>
Unfortunately, it's not possible for UString to compare equal to its
equivalent string, for two reasons: (1) System.String.Equals cannot be
changed, and (2) UString.GetHashCode cannot return the same value as
String.GetHashCode without actually generating a String object, which
would be inefficient (String.GetHashCode cannot be emulated because it
changes between versions of the .NET framework and even between 32- and
64-bit builds.)
<para/>
TODO: add Right, Normalize, EndsWith, FindLast, ReplaceAll, etc.
</remarks>
</member>
<member name="T:Loyc.Collections.IBRange`1">
<summary>A bidirectional range. Allows you to read or remove the first
or last element in a range.</summary>
<remarks>
The bidirectional range interface is useful for supporting
data structures such as doubly-linked lists that have a front and a
back but no efficient access to the middle.
<para/>
Please see <see cref="T:Loyc.Collections.IFRange`1"/> for general documentation about ranges.
</remarks>
</member>
<!-- Badly formed XML comment ignored for member "T:Loyc.Collections.IFRange`1" -->
<member name="M:Loyc.Collections.IFRange`1.PopFront(System.Boolean@)">
<summary>Removes the first item from the range and returns it.</summary>
<param name="fail">Receives the current value of IsEmpty.</param>
<returns>The first item of the range, or default(T) if IsEmpty.</returns>
<remarks>This method is a little unweildy in plain C#, but in EC# it
will be a bit more convenient to use via extension methods like
<c>PopFirst(ref this Range range, T defaultValue)</c> and
<c>PopFirst(ref this Range range)</c>, which are illegal in plain C#.
<para/>
I wanted to give this method the signature "bool PopFirst(out T first)"
but the generic parameter "T" is covariant, i.e. it is marked "out T"
which, ironically, is not compatible with "out T" parameters, only with
return values.
</remarks>
</member>
<member name="P:Loyc.Collections.IFRange`1.IsEmpty">
<summary>Returns true if the range has no items left, false if not.</summary>
</member>
<member name="P:Loyc.Collections.IFRange`1.Front">
<summary>Returns the first value in the range, without popping it.</summary>
<exception cref="T:Loyc.Collections.EmptySequenceException">The sequence is empty.</exception>
<remarks>
A possible default implementation:
<pre>
T Front { get { return Range.PopFront(Clone()); } }
</pre>
</remarks>
</member>
<member name="M:Loyc.Collections.IBRange`1.PopBack(System.Boolean@)">
<summary>Removes the last item from the range and returns it.</summary>
<param name="fail">Receives the current value of IsEmpty.</param>
<returns>The first item of the range, or default(T) if IsEmpty.</returns>
<remarks>The remarks of <see cref="!:PopFirst"/> apply to this method.</remarks>
</member>
<member name="P:Loyc.Collections.IBRange`1.Back">
<summary>Returns the value of the last item in the range.</summary>
<exception cref="T:Loyc.Collections.EmptySequenceException">The sequence is empty.</exception>
<remarks>
A reasonable default implementation:
<pre>
T Back { get { return Range.PopBack(Clone()); } }
</pre>
</remarks>
</member>
<member name="M:Loyc.UString.#ctor(System.String,System.Int32,System.Int32)">
<summary>Initializes a UString slice.</summary>
<exception cref="T:System.ArgumentException">The start index was below zero.</exception>
<remarks>The (start, count) range is allowed to be invalid, as long
as 'start' is zero or above.
<ul>
<li>If 'count' is below zero, or if 'start' is above the original Length,
the Count of the new slice is set to zero.</li>
<li>if (start + count) is above the original Length, the Count of the new
slice is reduced to <c>list.Length - start</c>.</li>
</ul>
</remarks>
</member>
<member name="M:Loyc.UString.DecodeAt(System.Int32)">
<summary>Returns the UCS code point that starts at the specified index.</summary>
<param name="index">Code unit index at which to decode.</param>
<returns>The code point starting at this index, or a negative number.</returns>
<exception cref="T:System.IndexOutOfRangeException">Oops.</exception>
<remarks>
If decoding fails, either because the index points to the "middle" of a
multi-code-unit sequence or because the string contains an invalid
UTF sequence, this method returns a negative value (the bitwise 'not' of
the invalid char).
</remarks>
</member>
<member name="M:Loyc.UString.Substring(System.Int32,System.Int32)">
<summary>Synonym for Slice()</summary>
</member>
<member name="M:Loyc.UString.Find(System.Int32,System.Boolean)">
<summary>Finds the specified UCS-4 character.</summary>
<returns>returns a range from the first occurrence of 'what' to the
original end of this UString. If the character is not found, an empty
string (slicing the end of this range) is returned.</returns>
</member>
<member name="M:Loyc.UString.Find(Loyc.UString,System.Boolean)">
<summary>Finds the specified string within this string.</summary>
<returns>Returns a range from the first occurrence of 'what' to the
original end of this UString. If 'what' is not found, an empty string
(slicing the end of this range) is returned.</returns>
</member>
<member name="M:Loyc.UString.ToUpper">
<summary>Converts the string to uppercase using the 'invariant' culture.</summary>
</member>
<member name="M:Loyc.UString.StartsWith(Loyc.UString,System.Boolean)">
<summary>Determines whether this string starts with the specified other
string.</summary>
<returns>true if this string starts with the contents of 'what'</returns>
</member>
<member name="M:Loyc.UString.Replace(Loyc.UString,Loyc.UString,System.Boolean,System.Int32)">
<summary>Returns a new string in which all occurrences (or a specified
number of occurrences) of a specified string in the current instance
are replaced with another specified string.</summary>
<param name="what"></param>
<param name="replacement"></param>
<param name="ignoreCase"></param>
<param name="maxReplacements"></param>
<returns>Returns a new string with replacements made, or the same
string if no replacements occurred.</returns>
</member>
<member name="P:Loyc.UString.Item(System.Int32)">
<summary>Returns the code unit (16-bit value) at the specified index.</summary>
<exception cref="T:System.IndexOutOfRangeException">Oops.</exception>
</member>
<member name="P:Loyc.UString.Item(System.Int32,System.Char)">
<summary>Returns the code unit (16-bit value) at the specified index,
or a default value if the specified index was out of range.</summary>
</member>
<member name="T:Loyc.ValueComparer`1">
<summary>You'd think the .NET framework would have a built-in method--even
a CIL opcode--to bitwise-compare two values. Not supporting bitwise compare
is, in my opinion, one of several mind-bogglingly dumb decisions in the
CLR. Instead, all you can do is call ValueComparer.Default.Equals(a, b).
</summary>
<remarks>
The Default.Equals method is a virtual function call, but as far as I know,
in generic code there is no way to avoid this while supporting any type T.
<para/>
If T is a reference type, it compares the two references using
ReferenceComparer. If T is a struct then this class does not currently
perform a bitwise comparison, as it just uses EqualityComparer(T).Default;
however, the comparison ends up being bitwise for most value types. In the
future somebody should write a fast "unsafe" bitwise comparer for value
types that do not implement IEquatable, because the default implementation
of Equals is documented to use reflection, so we can expect that it is
extremely slow.
</remarks>
</member>
<member name="T:Loyc.MiniTest.TestFixtureAttribute">
<summary>Identifies a class that contains unit tests, or methods that
return other tests or test fixtures.</summary>
<remarks>
The MiniTest runner will ignore any class that does not have the
[TestFixture] attribute and is not named according to a recognized pattern,
such as My_TestFixture.
</remarks>
<example>
[TestFixture]
public class ExampleClass {...}
</example>
</member>
<member name="P:Loyc.MiniTest.TestFixtureAttribute.Description">
<summary>
Descriptive text for this fixture
</summary>
</member>
<member name="T:Loyc.MiniTest.TestAttribute">
<summary>Identifies a method that contains a unit test, or that
returns other tests or test fixtures.</summary>
<remarks>
In addition to standard tests (which return void), the MiniTest runner
is planned to support [Test] methods with other return values:
<ul>
<li>A test can return a string, which describes the result of the test.</li>
<li>A test can return an Action (or any other delegate that takes no
arguments), which is treated as a sub-test and executed. Sub-tests are
run without set-up or tear-down steps.</li>
<li>A test can return an object that does not implement IEnumerable, which
the test runner will assume is a test fixture. The object will be scanned
for test methods to execute.</li>
<li>A test can return an object that implements IEnumerable, which the
test runner will scan to find tests and test fixtures to execute.</li>
<li>A test can return a KeyValuePair(TKey, TValue) or DictionaryEntry.
In that case pair's Value is processed as though it were the return value,
and the key is a status message.</li>
</ul>
These features give the MiniTest runner powerful capabilities while keeping
it simple. However, please note that NUnit doesn't offer this feature.
<para/>
MiniTest allows tests to be static methods if they are inside a test
fixture. However, when test objects are returned from a [Test] method,
they are not scanned for static methods.
<para/>
If multiple tests return the same test fixture instance, directly or
indirectly, MiniTest runner will avoid running the test fixture instance
multiple times, but it can show the results at multiple places in the
result tree, which can be used to construct multiple "views" of the test
results. However, if a test fixture is nested within itself, the nested
instance is excluded from the result tree.
<para/>
If a TestFixture class contains only a single "test suite" method (a
method that returns tests), MiniTest merges that method with the class in
the tree view. For example, if the class "MyTests" has a single method
"GetTests", the tree view will use one line for "MyTests.GetTests" rather
than separating out GetTests as a child of MyTests.
</remarks>
<example>
[Test]
public void MyTest() {...}
</example>
</member>
<member name="P:Loyc.MiniTest.TestAttribute.Description">
<summary>
Descriptive text for this test
</summary>
</member>
<member name="P:Loyc.MiniTest.TestAttribute.AllowParallel">
<summary>
Indicates whether this test can be run in parallel with other tests
in different test fixtures.
</summary>
<remarks>This property does not exist in NUnit.</remarks>
</member>
<member name="T:Loyc.MiniTest.SetUpAttribute">
<summary>
Marks a method that is to be called prior to each test in a test fixture.
</summary>
</member>
<member name="T:Loyc.MiniTest.TearDownAttribute">
<summary>
Marks a method that is to be called after each test in a test fixture.
</summary>
</member>
<member name="T:Loyc.MiniTest.BenchmarkAttribute">
<summary>
Marks a benchmark test, which exists to test performance. Benchmark tests
are often run multiple times to obtain an average running time.
</summary>
<remarks>This attribute does not exist in NUnit.</remarks>
</member>
<member name="P:Loyc.MiniTest.BenchmarkAttribute.RepeatForMs">
<summary>Gets or sets the recommended minimum length of time to
run the test. The test runner will run the test repeatedly until
the total time elapsed exceeds this number.</summary>
</member>
<member name="P:Loyc.MiniTest.BenchmarkAttribute.MinTrials">
<summary>Gets or sets the recommended minimum number of times to run
the benchmark in order to get an average. If this property is left
at the default value (null), the test runner can decide.</summary>
<remarks>If RepeatForMs is also specified, the number of trials can
be increased to reach the requested running time.</remarks>
</member>
<member name="T:Loyc.MiniTest.AssertionException">
<summary>
Thrown when an assertion fails during a call to a method of <see cref="T:Loyc.MiniTest.Assert"/>.
</summary>
</member>
<member name="T:Loyc.MiniTest.IgnoreException">
<summary>Thrown by <see cref="M:Loyc.MiniTest.Assert.Ignore(System.String,System.Object[])"/>.</summary>
</member>
<member name="T:Loyc.MiniTest.InconclusiveException">
<summary>Thrown by <see cref="M:Loyc.MiniTest.Assert.Inconclusive(System.String,System.Object[])"/>.</summary>
</member>
<member name="T:Loyc.MiniTest.SuccessException">
<summary>Thrown by <see cref="M:Loyc.MiniTest.Assert.Success(System.String,System.Object[])"/>.</summary>
</member>
<member name="T:Loyc.MiniTest.Assert">
<summary>
The Assert class contains a collection of static methods that mirror
the most common assertions used in NUnit.
</summary>
<remarks>
WORK IN PROGRESS. TEST RUNNER IS NOT WRITTEN YET.
<para/>
This class is mostly a drop-in replacement for "old-style" NUnit tests,
i.e. those that do not use constraint classes or the "Is" class.
<para/>
Some methods were dropped to keep this class small. Use the full NUnit
framework if the remaining methods are not sufficient for you.
<ul>
<li>When the same assertion was known by multiple similar names (e.g.
True and IsTrue), I kept only one of the names. However, I did keep
That(), Expect() and IsTrue() even though they all do the same thing.</li>
<li>Some less-common overloads that take a format string and arguments
were dropped.</li>
<li>Some overloads were dropped when the compiler can automatically
select a different overload instead. In particular, most overloads that
take a message string (without arguments) were dropped. Code that relied
on those overloads will still compile, because the compiler will
construct an empty argument list and call the overload that takes a
variable argument list.</li>
</ul>
</remarks>
</member>
<member name="M:Loyc.MiniTest.Assert.#ctor">
<summary>
You may find it useful to derive a test fixture from Assert so that
you do not need to prefix every test with "Assert."
</summary>
</member>
<member name="M:Loyc.MiniTest.Assert.Fail(System.String,System.Object[])">
<summary>Fails a test via StopTestHandler, which, by default,
throws an AssertionException.</summary>
</member>
<member name="M:Loyc.MiniTest.Assert.Fail(System.String)">
<summary>Fails a test by invoking <see cref="!:FailHandler"/>.Value(),
which, by default, throws an AssertionException.</summary>
</member>
<member name="M:Loyc.MiniTest.Assert.Ignore(System.String,System.Object[])">
<summary>Stops a test via StopTestHandler, which, by default, throws
an IgnoreException. This causes the test to be reported as ignored.</summary>
</member>
<member name="M:Loyc.MiniTest.Assert.Inconclusive(System.String,System.Object[])">
<summary>Stops a test via StopTestHandler, which, by default, throws
an InconclusiveException. This causes the test to be reported as
inconclusive.</summary>
</member>
<member name="M:Loyc.MiniTest.Assert.Success(System.String,System.Object[])">
<summary>Stops a test via StopTestHandler, which, by default,
throws a SuccessException.</summary>
</member>
<member name="M:Loyc.MiniTest.Assert.Fail">
<summary>Short for Fail("").</summary>
</member>
<member name="M:Loyc.MiniTest.Assert.Ignore">
<summary>Short for Ignore("").</summary>
</member>
<member name="M:Loyc.MiniTest.Assert.Inconclusive">
<summary>Short for Inconclusive("").</summary>
</member>
<member name="M:Loyc.MiniTest.Assert.Success">
<summary>Short for Success("").</summary>
</member>
<member name="M:Loyc.MiniTest.Assert.Equals(System.Object,System.Object)">
<summary>
Equals() is inherited from object; you probably want to call AreEqual instead.
</summary>
</member>
<member name="M:Loyc.MiniTest.Assert.ReferenceEquals(System.Object,System.Object)">
<summary>
Verifies that two references are equal.
</summary>
</member>
<member name="M:Loyc.MiniTest.Assert.That(System.Boolean,System.String,System.Object[])">
<summary>Calls Fail(message, args) if condition is false.</summary>
</member>
<member name="M:Loyc.MiniTest.Assert.That(System.Boolean,System.String)">
<summary>Calls Fail(message) if condition is false.</summary>
</member>
<member name="M:Loyc.MiniTest.Assert.That(System.Boolean)">
<summary>Calls Fail() if condition is false.</summary>
</member>
<member name="M:Loyc.MiniTest.Assert.Expect(System.Boolean)">
<summary>Calls Fail() if condition is false.</summary>
</member>
<member name="M:Loyc.MiniTest.Assert.Throws(System.Type,System.Action,System.String,System.Object[])">
<summary>
Verifies that a delegate throws a particular exception when called.
</summary>
<param name="expectedExceptionType">The exception Type expected</param>
<param name="code">A method to run</param>
<param name="message">The message that will be displayed on failure</param>
<param name="args">Arguments to be used in formatting the message</param>
</member>
<member name="M:Loyc.MiniTest.Assert.Catch(System.Action,System.String,System.Object[])">
<summary>
Verifies that a delegate throws an exception when called and returns it.
</summary>
<param name="code">A method to run</param>
<param name="message">The message that will be displayed on failure</param>
<param name="args">Arguments to be used in formatting the message</param>
</member>
<member name="M:Loyc.MiniTest.Assert.Catch(System.Action)">
<summary>
Verifies that a delegate throws an exception when called
and returns it.
</summary>
<param name="code">A TestDelegate</param>
</member>
<member name="M:Loyc.MiniTest.Assert.DoesNotThrow(System.Action,System.String,System.Object[])">
<summary>
Verifies that a delegate does not throw an exception
</summary>
</member>
<member name="M:Loyc.MiniTest.Assert.DoesNotThrow(System.Action)">
<summary>
Verifies that a delegate does not throw an exception.
</summary>
<param name="code">A TestSnippet delegate</param>
<param name="message">The message that will be displayed on failure</param>
</member>
<member name="M:Loyc.MiniTest.Assert.Contains(System.Object,System.Collections.IEnumerable,System.String,System.Object[])">
<summary>
Asserts that an object is contained in a list.
</summary>
<param name="expected">The expected object</param>
<param name="actual">The list to be examined</param>
<param name="message">The message to display in case of failure</param>
<param name="args">Array of objects to be used in formatting the message</param>
</member>
<member name="M:Loyc.MiniTest.Assert.Contains(System.Object,System.Collections.IEnumerable)">
<summary>
Asserts that an object is contained in a list.
</summary>
<param name="expected">The expected object</param>
<param name="actual">The list to be examined</param>
</member>
<member name="T:Loyc.MemoizedTypeName">
<summary>.NET Framework reflection doesn't offer complete type names for
generic types such as "List<int>" (the Type.Name value of that class is
"List`1"). <see cref="M:Loyc.MemoizedTypeName.GetGenericName(System.Type)"/> fills in the gap, and also saves the
computed name for fast repeated lookups.</summary>
</member>
<member name="M:Loyc.MemoizedTypeName.GetGenericName(System.Type)">
<summary>Computes a short language-agnostic name for a type, including
generic parameters, e.g. GenericName(typeof(int)) is "Int32";
GenericName(typeof(Dictionary<int, string>)) is
"Dictionary<Int32, String>".</summary>
<param name="type">Type whose name you want</param>
<returns>Name with generic parameters, as explained in the summary.</returns>
<remarks>The result is memoized for generic types, so that the name is
computed only once.</remarks>
</member>
<member name="M:Loyc.MemoizedTypeName.ComputeGenericName(System.Type)">
<summary>Computes a type's name without memoization.</summary>
</member>
<member name="M:Loyc.MemoizedTypeName.NameWithGenericParams(System.Type)">
<summary>Extension method on Type that is an alias for the <see cref="!:ShortName"/> method.</summary>
</member>
<!-- Badly formed XML comment ignored for member "T:Loyc.Math.IIntMath`1" -->
<!-- Badly formed XML comment ignored for member "T:Loyc.Math.ISignedMath`1" -->
<member name="T:Loyc.Math.IMath`1">
<summary>
Provides operations available on all system numeric types (int, uint, double,
etc.); see also <see cref="T:Loyc.Math.ISignedMath`1"/>, <see cref="T:Loyc.Math.IUIntMath`1"/>,
<see cref="T:Loyc.Math.IIntMath`1"/> and <see cref="T:Loyc.Math.IFloatMath`1"/>.
</summary>
<typeparam name="T">An integer, fixed-point, rational or floating-point numeric type</typeparam>
<remarks>
List of operations and properties: From, CompareTo, Equals, IsLess,
IsLessOrEqual, Abs, Min, Max, MinValue, MaxValue, Epsilon, PositiveInfinity,
NegativeInfinity, IsSigned, Increment, Decrement, NextHigher, NextLower,
Add, Subtract, Zero, One, Multiply, Divide, ShiftLeft, ShiftRight, Sqrt,
Square.
<para/>
Also available as extension methods: IsGreater, IsGreaterOrEqual
<para/>
It is commonly thought that integer types do not support square root.
Obviously, the accuracy of Sqrt on integers is limited, but Sqrt(uint) and
Sqrt(ulong) are still provided in Loyc.Essentials.
</remarks>
</member>
<member name="T:Loyc.Math.INumTraits`1">
<summary>This interface provides information about a numeric type T.</summary>
<typeparam name="T">A numeric type</typeparam>
</member>
<member name="P:Loyc.Math.IOneProvider`1.One">
<summary>Returns the "one" or identity value of this type.</summary>
</member>
<member name="M:Loyc.Math.INumTraits`1.IsInfinity(`0)">
<summary>Returns true if the given value is infinite.</summary>
<remarks>Types that do not have an infinity value always return false
from this method.</remarks>
</member>
<member name="M:Loyc.Math.INumTraits`1.IsNaN(`0)">
<summary>Returns true if the given value is not a number (can only be true for floats).</summary>
</member>
<member name="P:Loyc.Math.INumTraits`1.MinValue">
<summary>Minimum value of this type above negative infinity.</summary>
</member>
<member name="P:Loyc.Math.INumTraits`1.MaxValue">
<summary>Maximum value of this type below infinity.</summary>
</member>
<member name="P:Loyc.Math.INumTraits`1.Epsilon">
<summary>Smallest representable positive value of T (1 for integer types).</summary>
</member>
<member name="P:Loyc.Math.INumTraits`1.PositiveInfinity">
<summary>Returns positive infinity, or MaxValue for types that cannot represent infinity.</summary>
</member>
<member name="P:Loyc.Math.INumTraits`1.NegativeInfinity">
<summary>Returns negative infinity, or throws NotSupportedException if T is unsigned.</summary>
<exception cref="T:System.NotSupportedException">T is unsigned.</exception>
</member>
<member name="P:Loyc.Math.INumTraits`1.NaN">
<summary>Not-a-number or null representation for this type.</summary>
<exception cref="T:System.NotSupportedException">There is no null or NaN value for type T.</exception>
</member>
<member name="P:Loyc.Math.INumTraits`1.IsSigned">
<summary>Returns true if T can represent negative values.</summary>
</member>
<member name="P:Loyc.Math.INumTraits`1.IsFloatingPoint">
<summary>Returns true if T is floating-point, meaning that it can
represent very large and very small numbers, despite possibly limited
precision. Returns false for fixed-point and integer-rational types.</summary>
</member>
<member name="P:Loyc.Math.INumTraits`1.IsInteger">
<summary>Returns true if the type represents only whole numbers.</summary>
</member>
<member name="P:Loyc.Math.INumTraits`1.IsOrdered">
<summary>Returns true for "normal" numbers, false for ones that aren't
necessarily comparable (notably complex numbers).</summary>
</member>
<member name="P:Loyc.Math.INumTraits`1.SignificantBits">
<summary>Returns the normal maximum number of significant (mantissa)
bits for this type (not counting the sign bit), or int.MaxValue for
unlimited-size types.</summary>
</member>
<member name="P:Loyc.Math.INumTraits`1.MaxIntPowerOf2">
<summary>Returns the maximum power-of-two-minus-one that can be
represented by this type, e.g. for Int32 it's 31, and for UInt32 it's
32.</summary>
</member>
<member name="P:Loyc.Math.INumTraits`1.MaxInt">
<summary>Returns the maximum integer that this type can represent.</summary>
<remarks>If the maximum integer exceeds ulong.MaxValue, this returns
ulong.MaxValue.</remarks>
</member>
<member name="P:Loyc.Math.INumTraits`1.MinInt">
<summary>Returns the minimum integer that this type can represent.</summary>
<remarks>If the minimum is less than long.MinValue, this returns
long.MinValue.</remarks>
</member>
<member name="T:Loyc.Math.INumConverter`1">
<summary>
Provides methods for converting common numeric types to another numeric type "T".
</summary>
<typeparam name="T">A numeric type</typeparam>
<remarks>Methods for converting type T to standard numeric types would be
redundant, because standard numeric types already implement IConvertible for
this purpose. To use IConvertible in generic code, add IConvertible as a
type constraint on the numeric type.</remarks>
</member>
<member name="T:Loyc.Math.IInrementer`1">
<summary>Provides increment, decrement, and next/previous-representable-
value operations.</summary>
<typeparam name="T">A numeric type.</typeparam>
<remarks>Implementations may or may not detect overflow.</remarks>
</member>
<member name="M:Loyc.Math.IInrementer`1.Incremented(`0)">
<summary>Returns a + 1.</summary>
</member>
<member name="M:Loyc.Math.IInrementer`1.Decremented(`0)">
<summary>Returns a - 1.</summary>
</member>
<member name="M:Loyc.Math.IInrementer`1.NextHigher(`0)">
<summary>Returns the next representable number higher than a.</summary>
</member>
<member name="M:Loyc.Math.IInrementer`1.NextLower(`0)">
<summary>Returns the next representable number lower than a.</summary>
</member>
<member name="T:Loyc.Math.IField`1">
<summary>
This defines a Field with the operations +,-,*,/
Axioms that have to be satisified by the operations:
The group axioms for +
The group axioms for *
Associativity: a * (b*c) = (a*b) * c
Distributivity:
a * (b+c) = (a*b) + (a*c)
(a+b) * c = (a*c) + (b*c)
</summary>
</member>
<member name="T:Loyc.Math.IRing`1">
<summary>
This defines a Ring with the operations +,*
Axioms that have to be satisified by the operations:
The group axioms for +
Associativity of *: a * (b*c) = (a*b) * c
Neutral element of *: Multiply(One,a)==a for all a in T
Distributivity:
a * (b+c) = (a*b) + (a*c)
(a+b) * c = (a*c) + (b*c)
</summary>
</member>
<member name="T:Loyc.Math.IMultiply`1">
<summary>Provides the multiplication operation and the multiplicative identity, one.</summary>
</member>
<member name="T:Loyc.Math.IMultiplicationGroup`1">
<summary>
This defines a Group with the operation *, the neutral element One,
the inverse Inverse and an operation / that is defined in terms of the inverse.
Axioms that have to be satisified by the operations:
Commutativity of multiplication: Multiply(a,b)=Multiply(b,a) for all a,b in T
Associativity of multiplication: Multiply(Multiply(a,b),c)=Multiply(a,Multiply(b,c))
Inverse of multiplication: Multiply(a,Inverse(a))==One for all a in T
Divison: Divide(a,b)==Multiply(a,Inverse(b)) for all a in T
Neutral element: Multiply(One,a)==a for all a in T
</summary>
<remarks>
ShiftLeft and ShiftRight operations are commonly thought of as binary
operations, but some algorithms need to multiply numbers by powers of two
and want to do so efficiently, while still supporting floating-point types.
Therefore it makes sense to offer ShiftLeft ("multiply by a power of two")
and ShiftRight ("divide by a power of two") operators as part of the
multiple/divide interface, not just <see cref="T:Loyc.Math.IBinaryMath`1"/>. Even
floating-point types can support these two operations efficiently by
directly modifying the exponent part of the floating-point representation.
</remarks>
</member>
<member name="T:Loyc.Math.IHasRoot`1">
<summary>Provides the Sqrt operation and its inverse, Square.</summary>
</member>
<member name="T:Loyc.Math.IBinaryMath`1">
<summary>Provides additional bit-oriented integer operations.</summary>
<typeparam name="T">An integer or integer-based types.</typeparam>
</member>
<member name="T:Loyc.Math.IBitwise`1">
<summary>Provides the standard set of bitwise operators.</summary>
<typeparam name="T">An integer or bit array type.</typeparam>
</member>
<member name="M:Loyc.Math.IBinaryMath`1.ShiftLeft(`0,System.Int32)">
<summary>Shifts 'a' left by the specified number of bits.</summary>
<remarks>A shift amount A negative shift amount produces undefined results</remarks>
</member>
<member name="M:Loyc.Math.IBinaryMath`1.ShiftRight(`0,System.Int32)">
<summary>Shifts 'a' right by the specified number of bits.</summary>
</member>
<member name="M:Loyc.Math.IBinaryMath`1.CountOnes(`0)">
<summary>Returns the number of '1' bits in 'a'.</summary>
</member>
<member name="M:Loyc.Math.IBinaryMath`1.Log2Floor(`0)">
<summary>
Returns the floor of the base-2 logarithm of x. e.g. 1024 -> 10, 1000 -> 9
</summary><remarks>
The return value is int.MinValue for an input of zero (for which the
logarithm is technically undefined.)
</remarks>
</member>
<!-- Badly formed XML comment ignored for member "T:Loyc.Math.IUIntMath`1" -->
<member name="T:Loyc.Math.IFloatMath`1">
<summary>Provides operations available on floating-point types
(float and double), including trigonometry and exponentiation.
</summary>
<typeparam name="T">A floating-point type</typeparam>
<remarks>Algorithms that support both floating and fixed-point should
require <see cref="T:Loyc.Math.IRationalMath`1"/> instead.</remarks>
</member>
<member name="T:Loyc.Math.IRationalMath`1">
<summary>
Use this interface for floating-point, fixed-point, and rational types.
Rational types support reciprocal and negation.
</summary>
</member>
<member name="T:Loyc.Math.ITrigonometry`1">
<summary>Provides trigonometry operations.</summary>
</member>
<member name="T:Loyc.Math.IExp`1">
<summary>Provides power, logarithm, raise-e-to-exponent (Exp) and logarithm-of-e (Log) operations.</summary>
</member>
<member name="T:Loyc.Collections.WeakKeyDictionary`2">
<summary>A dictionary with weak keys.</summary>
<remarks>Source: datavault project. License: Apache License 2.0</remarks>
</member>
<member name="T:Loyc.Collections.BaseDictionary`2">
<summary>Base class for user-defined dictionaries</summary>
<remarks>Modified version of source: datavault project. License: Apache License 2.0.</remarks>
</member>
<member name="T:System.Collections.Generic.IReadOnlyDictionary`2">
<summary>Read-only dictionary interface defined in .NET 4.5</summary>
</member>
<member name="T:Loyc.Collections.Impl.InternalDList`1">
<summary>A compact auto-enlarging deque structure that is intended to be
used within other data structures. It should only be used internally in
"private" or "protected" members of low-level code. In most cases, you
should use <see cref="T:Loyc.Collections.DList`1"/> instead.
</summary>
<remarks>
This type is implemented with what is commonly called a "circular buffer".
There is a single array plus a "start index" and a count. The array may or
may not be divided into two "halves", depending on the circumstances.
The first element of the DList (returned from this[0] and from the
First property) is located at the start index of the array; and if the
index + count is greater than the array size, then the end of the DList
wraps around to the beginning of the array.
<para/>
InternalDeque is a struct, not a class, in order to save memory; and for
maximum performance, it asserts rather than throwing an exception
when an incorrect array index is used (the one exception is the iterator,
which throws in case the collection is modified during enumeration; this
is for the sake of <see cref="T:Loyc.Collections.DList`1"/>.) For these and other reasons, one
should not expose it in a public API, and it should only be used when
performance trumps all other concerns.
<para/>
Also, do not use the default contructor. Always specify an initial
capacity or copy InternalDeque.Empty so that the internal array gets a
value. All methods in this structure assume _array is not null.
<para/>
This class does not implement <see cref="T:Loyc.Collections.IDeque`1"/> and <see cref="T:System.Collections.Generic.IList`1"/> in order to help you not to shoot yourself in the foot.
The problem is that any extension methods used with those interfaces that
change the list, such as PopLast(), malfunction because the structure is
implicitly boxed, producing a shallow copy. By not implementing those
interfaces, the extension methods are not available, ensuring you don't
accidently box the structure. You can always call <see cref="!:ToDList"/>
to construct a <see cref="T:Loyc.Collections.DList`1"/> in O(1) time, if you need those
interfaces.
<para/>
You may be curious why <see cref="T:Loyc.Collections.Impl.InternalList`1"/>, in contrast, DOES
implement <see cref="T:System.Collections.Generic.IList`1"/>. It's because there is no way to make
<see cref="T:System.Collections.Generic.List`1"/> from <see cref="T:Loyc.Collections.Impl.InternalList`1"/> in O(1) time;
so boxing the <see cref="T:Loyc.Collections.Impl.InternalList`1"/> is the only fast way to get
an instance of <see cref="T:System.Collections.Generic.IList`1"/>.
</remarks>
</member>
<member name="M:Loyc.Collections.Impl.InternalDList`1.Add(`0)">
<summary>An alias for PushLast().</summary>
</member>
<member name="M:Loyc.Collections.Impl.InternalDList`1.AsDList">
<summary>Returns a <see cref="T:Loyc.Collections.DList`1"/> wrapped around this list.</summary>
<remarks>WARNING: in order to run in O(1) time, the two lists
(InternalDList and DList) share the same array, but not the same
internal state. You must stop using one list after modifying the
other, because changes to one list will have strange effects in
the other list.</remarks>
</member>
<member name="T:Loyc.Collections.ListChangeInfo`1">
<summary>Contains information about how a collection is about to change.</summary>
<typeparam name="T">Type of element in the collection</typeparam>
<remarks>
In contrast to <see cref="T:System.Collections.Specialized.NotifyCollectionChangedEventArgs"/>, this object
represents changes that are about to happen, not changes that have happened
already.
</remarks>
<seealso cref="T:Loyc.Collections.INotifyListChanging`1"/>
</member>
<member name="M:Loyc.Collections.ListChangeInfo`1.#ctor(System.Collections.Specialized.NotifyCollectionChangedAction,System.Int32,System.Int32,Loyc.Collections.IListSource{`0})">
<summary>Initializes the members of <see cref="T:Loyc.Collections.ListChangeInfo`1"/>.</summary>
</member>
<member name="F:Loyc.Collections.ListChangeInfo`1.Action">
<summary>Gets a value that indicates the type of change being made to
the collection.</summary>
</member>
<member name="F:Loyc.Collections.ListChangeInfo`1.Index">
<summary>Gets the index at which the add, remove, or change operation starts.</summary>
</member>
<member name="F:Loyc.Collections.ListChangeInfo`1.SizeChange">
<summary>Gets the amount by which the collection size changes. When
items are being added, this is positive, and when items are being
removed, this is negative. This is 0 when existing items are only being
replaced.</summary>
</member>
<member name="F:Loyc.Collections.ListChangeInfo`1.NewItems">
<summary>Represents either new items that are being added to the
collection, or items that are about to replace existing items in
the collection. This member is null or empty when items are being
removed.</summary>
</member>
<member name="T:Loyc.Collections.NestedEnumerator`2">
<summary>An enumerator that helps enumerate tree data structures. It
maintains a virtual call stack that avoids the performance hit of using
nested "yield return" statements in C#.</summary>
<typeparam name="Frame">Frame data structure; represents the current 'depth'
in a tree data structure, or the current 'stack frame' on a virtual stack.
Typically, this parameter will either be <see cref="T:Loyc.Collections.Impl.EnumeratorFrame`1"/> or
a struct that implements <see cref="T:Loyc.Collections.Impl.IEnumeratorFrame`2"/>.</typeparam>
<typeparam name="T">Item data type returned by the enumerator.</typeparam>
<remarks>
This data type helps you solve the performance problem with using "yield
return" recursively ().
<para/>
To illustrate how to use <see cref="T:Loyc.Collections.NestedEnumerator`2"/> let's
consider the case of binary tree traversal. Suppose you define this data
structure to hold a subtree of a sorted binary tree of strings:
<code>
internal class StringNode : IEnumerable<string>
{
internal StringNode LeftChild;
internal string Value;
internal StringNode RightChild;
public IEnumerator<string> GetEnumerator() { ... }
}
</code>
You want to write an enumerator that returns all the strings in order.
So you write this method in the StringNode class:
<code>
public IEnumerator<string> GetEnumerator()
{
foreach(string item in LeftChild)
yield return item;
yield return Value;
foreach(string item in RightChild)
yield return item;
}
</code>
As explained in <a href="http://stackoverflow.com/questions/3969963/when-not-to-use-yield-return">
this web page</a>, this implementation will be slow, and it will get slower
and slower as the tree gets deeper.
<para/>
NestedEnumerator helps to solve this problem using a "virtual stack". It
keeps track of all the nested enumerators and always returns values from
the current, deepest enumerator. The enumerator objects are called "frames",
because they are "stack frames" on the virtual stack.
<para/>
Each enumerator implements <see cref="T:Loyc.Collections.Impl.IEnumeratorFrame`2"/> instead
of just <see cref="T:System.Collections.Generic.IEnumerator`1"/>. A normal enumerator can only do one
of two actions on each call to MoveNext(): it can return a T value, or stop.
But an <c>IEnumeratorFrame</c> can do one of three things: it can return a T
value, it can stop, or it can return a new (child) stack frame.
<para/>
You cannot use <c>yield return</c> with <c>NestedEnumerator</c> because it
is not supported by the C# compiler, so using <c>NestedEnumerator</c>
requires more developer effort. Here's how the GetEnumerator() method can
be implemented using <c>NestedEnumerator</c>:
<code>
public static IEnumerator<string> GetEnumerator()
{
return new NestedEnumerator<Frame, string>(new Frame(this));
}
struct Frame : IEnumeratorFrame<Frame, string>
{
StringNode self;
int step;
public Frame(StringNode self) { _self = self; step = 0; }
int MoveNext(ref Frame frame, ref T current)
{
switch(++step) {
case 1: frame = new Frame(self.LeftChild); return -1;
case 2: current = Value; return 1;
case 3: frame = new Frame(self.RightChild); return -1;
}
return 0;
}
}
</code>
The <c>NestedEnumerator</c> takes care of managing the stack and invoking
<c>MoveNext</c> on the deepest instance of <c>IEnumeratorFrame</c>.
<para/>
<see cref="T:Loyc.Collections.Impl.IEnumeratorFrame`2"/> is an unusual interface that
requires <c>Frame</c> to be derived from the interface itself. The purpose
of this design is to allow the <see cref="!:Frame"/> data type to be a struct,
which allows the virtual stack to consist of value types (structs), which
improves performance because a new object does not have to be allocated on
the heap for every stack frame. Also, if <c>Frame</c> is a struct,
NestedEnumerator can call <see cref="M:Loyc.Collections.Impl.IEnumeratorFrame`2.MoveNext(`0@,`1@)"/>
directly, rather than via interface dispatch, which also improves
performance.
</remarks>
</member>
<member name="T:Loyc.Collections.NestedEnumerable`2">
<summary>Helper type. You pass a cloneable <c>Frame</c> object to the
constructor, and then a copy of this <c>Frame</c> is used to construct a
new <see cref="T:Loyc.Collections.NestedEnumerator`2"/> each time the user calls
<see cref="M:Loyc.Collections.NestedEnumerable`2.GetEnumerator"/>.</summary>
</member>
<member name="T:Loyc.Collections.Impl.IEnumeratorFrame`2">
<summary>Helper interface for <see cref="T:Loyc.Collections.NestedEnumerator`2"/>.</summary>
<typeparam name="Frame">A data type that implements this interface.</typeparam>
<typeparam name="T">Type of items enumerated by this interface.</typeparam>
</member>
<member name="M:Loyc.Collections.Impl.IEnumeratorFrame`2.MoveNext(`0@,`1@)">
<summary>Enumerates the next item, or the next child collection.</summary>
<param name="frame">Current frame (on entry, 'frame' is the same as 'this').
To begin enumerating a child frame, this method must change 'frame' to the
desired child frame and return -1.</param>
<param name="current">Current item (on entry, 'current' is value most
recently enumerated by <see cref="T:Loyc.Collections.NestedEnumerator`2"/>.) To
enumerate an item, MoveNext must change the value of 'current' and
return 1.</param>
<returns>1 to enumerate 'current', 0 when there are no more items in
this frame's sequence, and any other value to enumerate a child frame.</returns>
</member>
<member name="T:Loyc.Collections.Impl.EnumeratorFrame`1">
<summary>A standard base class for enumerator frames used by
<see cref="!:NestedEnumerator<EnumeratorFrame<T>,T>"/>.</summary>
<typeparam name="T">Type of items enumerated by this class.</typeparam>
<remarks>
This base class should be used whenever more than one type of frame
will be present on <see cref="!:NestedEnumerator"/>'s internal stack of
frames.
<para/>
If the enumerator will only use a single type of frame, then
(in some cases) the frame data type can be a 'struct' to achieve higher
performance. But in that case, this class cannot be used.</remarks>
</member>
<member name="T:Loyc.WeakReference`1">
<summary>
Adds strong typing to WeakReference.Target using generics.
</summary>
</member>
<member name="M:Loyc.WeakReference`1.NewOrNullSingleton(`0)">
<summary>Returns a new WeakReference except that if target is null,
the WeakNullReference Singleton is returned instead.</summary>
</member>
<member name="T:Loyc.WeakNullReference`1">
<summary>Provides a weak reference to a null target object, which, unlike
other weak references, is always considered to be alive. This facilitates,
for instance, handling null dictionary values in WeakValueDictionary.</summary>
</member>
<member name="T:Loyc.Math.FPI8">
<summary>Fixed-point type based on Int32 with 8 fractional bits</summary>
</member>
<member name="T:Loyc.Math.FPI16">
<summary>Fixed-point type based on Int32 with 16 fractional bits</summary>
</member>
<member name="T:Loyc.Math.FPI23">
<summary>Fixed-point type based on Int32 with 23 fractional bits</summary>
</member>
<member name="T:Loyc.Math.FPL16">
<summary>Fixed-point type based on Int64 with 16 fractional bits</summary>
</member>
<member name="T:Loyc.Math.FPL32">
<summary>Fixed-point type based on Int64 with 32 fractional bits</summary>
</member>
<member name="T:Loyc.Collections.ISinkCollection`1">
<summary>Represents a write-only collection: you can modify it, but you
cannot learn what it contains.</summary>
</member>
<member name="T:Loyc.Collections.ISinkArray`1">
<summary>Represents a write-only array.</summary>
</member>
<member name="T:Loyc.Collections.ISinkList`1">
<summary>Represents a write-only indexable list class.</summary>
</member>
<member name="T:Loyc.Collections.SourceAsCollection`1">
<summary>
A read-only wrapper that implements ICollection(T) and ISource(T),
returned from <see cref="M:Loyc.Collections.LCExt.AsCollection``1(System.Collections.Generic.IReadOnlyCollection{``0})"/>
</summary>
</member>
<member name="T:Loyc.WrapperBase`1">
<summary>Abstract class that helps you implement wrappers by automatically
forwarding calls to Equals(), GetHashCode() and ToString().</summary>
</member>
<member name="M:Loyc.WrapperBase`1.Equals(System.Object)">
<summary>Returns true iff the parameter 'obj' is a wrapper around the same object that this object wraps.</summary>
<param name="obj">The object to compare with the current object.</param>
<remarks>If obj actually refers to the wrapped object, this method returns false to preserve commutativity of the "Equals" relation.</remarks>
</member>
<member name="M:Loyc.WrapperBase`1.GetHashCode">
<summary>Returns the hashcode of the wrapped object.</summary>
</member>
<member name="M:Loyc.WrapperBase`1.ToString">
<summary>Returns ToString() of the wrapped object.</summary>
</member>
<member name="T:Loyc.Collections.SelectListSource`2">
<summary>
Provides a modified view of an IListSource by transforming each element
on-demand. Objects of this type are returned from
<see cref="M:Loyc.Collections.LCExt.Select``2(Loyc.Collections.IListSource{``0},System.Func{``0,``1})"/>
</summary>
<typeparam name="T"></typeparam>
</member>
<member name="T:Loyc.Collections.ListSlice`1">
<summary>
A wrapper of a list that provides a view of a range of elements.
Objects of this type are returned from <see cref="M:Loyc.Collections.ListExt.Slice``1(System.Collections.Generic.IList{``0},System.Int32,System.Int32)"/>
</summary>
<remarks>
ListSlice provides both a <see cref="T:System.Collections.Generic.IList`1"/> interface and a
<see cref="T:Loyc.Collections.IRange`1"/> interface, and it is important not to confuse them.
The <see cref="T:System.Collections.Generic.IList`1"/> interface allows you to insert and remove items
from both the original list and the slice simultaneously. The
<see cref="T:Loyc.Collections.IRange`1"/> interface allows you to "Pop" items from the front
and back, but this reduces the length of the slice only, not the original
list.
</remarks>
</member>
<member name="T:Loyc.Collections.IRange`1">
<summary>A random-access range, also known as a "slice". Allows you to
narrow down the range like <see cref="T:Loyc.Collections.IBRange`1"/> does, and also
provides random access via <see cref="T:Loyc.Collections.IListSource`1"/>.</summary>
<remarks>
Please see <see cref="T:Loyc.Collections.IFRange`1"/> for general documentation about ranges.
</remarks>
</member>
<member name="T:Loyc.Collections.IListEx`1">
<summary>
This interface combines the original IList(T) interface with IArray(T)
and ISinkList(T), to make implementing all three more convenient.
</summary>
<remarks>
<see cref="T:Loyc.Collections.IArray`1"/> (a version of <see cref="T:Loyc.Collections.IListSource`1"/> that adds the writability of an
array) and <see cref="T:Loyc.Collections.ISinkList`1"/> are largely subsets of the IList(T) interface.
IListEx has two methods that IList(T) does not (TryGet() and GetIterator()); for
more information about GetIterator(), see the documentation of <see cref="!:IIterable<T>"/> and <see cref="T:Loyc.Collections.ICollectionEx`1"/>.
<para/>
Just as Iterator scans a collection faster than IEnumerator, TryGet() is intended to
accelerate access to a list at a specific index; see <see cref="T:Loyc.Collections.IListSource`1"/> for more information. TryGet() may be called
in different ways, through extension methods with the same name.
<para/>
Using <see cref="T:Loyc.Collections.ListExBase`1"/> as your base class can help you implement
this interface faster.
<para/>
TODO: compiler complains of ambiguity calling methos such as Add(), this[]; find workaround
</remarks>
</member>
<member name="T:Loyc.Collections.ICollectionEx`1">
<summary>
This interface combines the original ICollection(T) interface with
ISource(T) and ISinkCollection(T), a convenient way to implement all three.
</summary>
<remarks>
ISource(T) and ISinkCollection(T) are largely subsets of the ICollection(T)
interface. ICollectionEx has only one method that ICollection(T) does not
(GetIterator()), and the easiest way to implement it if you already wrote
GetEnumerator() is as follows:
<code>
public Iterator<T> GetIterator() { return GetEnumerator().ToIterator(); }
</code>
However, to gain the performance advantages of Iterable, it is better to
implement GetIterator() instead and use the following implementations of
GetEnumerator():
<code>
IEnumerator<T> IEnumerable<T>.GetEnumerator()
{
return GetEnumerator();
}
System.Collections.IEnumerator System.Collections.IEnumerable.GetEnumerator()
{
return GetEnumerator();
}
// The C# compiler will use this method in for-loops to avoid late binding.
public IteratorEnumerator<T> GetEnumerator()
{
return GetIterator().ToEnumerator();
}
</code>
</remarks>
</member>
<member name="T:Loyc.Collections.IAddRange`1">
<summary>An interface typically implemented alongside <see cref="T:System.Collections.Generic.ICollection`1"/>,
for collection types that can add multiple items in one method call.</summary>
</member>
<member name="T:Loyc.Collections.ICount">
<summary>Holds the Count property found in nearly all collection interfaces.</summary>
<remarks>
Microsoft has made this interface unusable by not defining it themselves in
.NET 4.5. Now that I've replaced my original interface
<code>
interface ISource<out T> : IEnumerable<T>, ICount {}
</code>
with Microsoft's IReadOnlyCollection(T), the compiler complains constantly about
"Ambiguity between IReadOnlyCollection(T).Count and ICount.Count". Eliminating
ICount from most places seems to be the only solution.
</remarks>
</member>
<member name="P:Loyc.Collections.ICount.Count">
<summary>Gets the number of items in the collection.</summary>
</member>
<member name="M:Loyc.Collections.ICollectionEx`1.RemoveAll(System.Predicate{`0})">
<summary>Removes the all the elements that match the conditions defined
by the specified predicate.</summary>
<param name="match">A delegate that defines the conditions of the elements to remove</param>
<returns>The number of elements removed.</returns>
</member>
<!-- Badly formed XML comment ignored for member "T:Loyc.Collections.IArray`1" -->
<member name="P:Loyc.Collections.IArray`1.Item(System.Int32)">
<summary>Gets or sets an element of the array-like collection.</summary>
<returns>The value of the array at the specified index.</returns>
<remarks>
This redundant indexer is required by C# because the compiler imagines
that the setter in <see cref="T:Loyc.Collections.ISinkArray`1"/> conflicts with the getter
in <see cref="T:Loyc.Collections.IListSource`1"/>.
</remarks>
</member>
<member name="M:Loyc.Collections.ListSlice`1.#ctor(System.Collections.Generic.IList{`0},System.Int32,System.Int32)">
<summary>Initializes a slice.</summary>
<exception cref="T:System.ArgumentException">The start index was below zero.</exception>
<remarks>The (start, count) range is allowed to be invalid, as long
as 'start' and 'count' are zero or above.
<ul>
<li>If 'start' is above the original Count, the Count of the new slice
is set to zero.</li>
<li>if (start + count) is above the original Count, the Count of the new
slice is reduced to <c>list.Count - start</c>. Note that the Count of
the slice will not increase if the list expands after the slice is
created.</li>
</ul>
</remarks>
</member>
<member name="T:Loyc.Localize">
<summary>
Localize is a global hook into which a string-mapping localizer can be
installed. It is designed to make internationalization exceptionally easy
for developers.
</summary><remarks>
All Loyc code should call this hook in order to localize text. Use it like
this:
<code>
string result = Localize.From("Hello, {0}", userName);
</code>. If you use this facility frequently in a given class, you may want
to shorten your typing using a static variable:
<code>
protected static readonly FormatterDelegate L = Localize.From;
</code>
Then you can simply write L("Hello, {0}", userName) instead. Either way,
whatever localizer is installed will look up the text in its database and
return a translation. If no translation to the end user's language is
available, an appropriate default translation should be returned: either the
original text, or a translation to some default language, e.g. English.
<p/>
Alternately, assuming you have the ability to change the table of
translations, you can use a Symbol in your code and call the other overload
of From() to look up the text that should be shown to the end user:
<code>
string result = Localize.From(GSymbol.Get("MY_STRING"));
string result = Localize.From(:MY_STRING); // Loyc syntax
</code>
This is most useful for long strings or paragraphs of text, but I expect
that some projects, as a policy, will use symbols for all localizable text.
<p/>
Localize.Formatter() is then called to make the completed string, unless the
variable argument list is empty. It is possible to perform formatting
separately, for example:
<code>
Console.WriteLine(Localize.From("{0} is {0:X} in hexadecimal"), N);
</code>
Here, writeline performs the formatting instead. However, Localize's
default formatter, Strings.Format, has an extra feature that the standard
formatter does not: named arguments. Here is an example:
<code>
...
string verb = Localize.From(IsFileLoaded ? "parse" : "load");
MessageBox.Show(
Localize.From("Not enough memory to {load/parse} '{filename}'."
{Message}", "load/parse", verb, "filename", FileName));
}
</code>
As you can see, named arguments are mentioned in the format string by
specifying an argument name such as {filename} instead of a number like
{0}. The variable argument list contains the same name followed by its
value, e.g. "filename", FileName. This feature gives you, the developer,
the opportunity to indicate to the translator person what a particular
argument is for.
<p/>
The translator must not change any of the arguments: the word "{filename}"
is not to be translated.
<p/>
At run-time, the format string with named arguments is converted to a
"normal" format string with numbered arguments. The above example would
become "Could not {1} the file: {3}" and then be passed to string.Format.
<h3>Design rationale</h3>
Many developers don't want to spend time writing internationalization or
localization code, and are tempted to write code that is only for one
language. It's no wonder, because it's a relative pain in the neck.
Microsoft suggests that code carry around a "ResourceManager" object and
directly request strings from it:
<code>
private ResourceManager rm;
rm = new ResourceManager("MyStrings", this.GetType().Assembly);
Console.Writeline(rm.GetString("HEXER"), N);
</code>
This approach has drawbacks:
* It may be cumbersome to pass around a ResourceManager instance between all
classes that might contain localizable strings; a global facility is
much more convenient.
* The programmer has to put all translations in the resource file;
consequently, writing the code is bothersome because the programmer has
to switch to the resource file and add the string to it. Someone reading
the code, in turn, can't tell what the string says and has to load up
the resource file to find out.
* It is nontrivial to change the localization manager; for instance, what if
someone wants to store translations in an .ini or .xml file rather than
inside the assembly? What if the user wants to centralize all
translations for a set of assemblies, rather than having separate
resources in each assembly?
* Keeping in mind that the guy in charge of translation is typically
different than the guys writing most of the code, it makes sense to keep
translations separate from everything else.
<p/>
The idea of the Localize facility is to convince programmers to support
localization by making it dead-easy to do. By default it is not connected to
any translator (it just passes strings through), so people who are only
writing a program for a one-language market can easily make their code
"multiligual-ready" without doing any extra work, since Localize.From() is
no harder to type than String.Format().
<p/>
The translation system itself is separate, and connected to Localize by a
delegate, for two reasons:
<ol>
<li>Multiple translation systems are possible. This class should be suitable
for any .NET program, and some programs using this utility will want to
plug-in a different localizer. </li>
<li>I personally don't have the time or expertise to write a localizer at
this time. So until I do, the Localize class will make my code ready for
translation, although not actually localized.</li>
</ol>
In the open source world, most developers don't have a team of translators
ready make translations for them. The idea of Loyc, for example, is that
many different individuals--not one big team--of programmers will create
and maintain features. By centralizing this translation facility, it should
be straightforward for a single multilingual individual to translate the
text of many Loyc extensions made by many different people.
<p/>
To facilitate this, I propose that in addition to a translator, a Loyc
extension should be made to figure out all the strings/symbols for which
translations are needed. To do this it would scan source code (at compile
time) for calls to methods in this class and generate a list of strings and
symbols needing translation. It would also have to detect certain calls that
perform translation implicity, such as ISimpleMessageSink.Write(). See
<see cref="T:Loyc.LocalizableAttribute"/>.
</remarks>
</member>
<member name="M:Loyc.Localize.Passthru(Loyc.Symbol,System.String)">
<summary>
This is the dummy translator, which is the default value of Localizer.
It passes strings through untranslated. A msgId symbol cannot be handled
so it is simply converted to a string.
</summary>
</member>
<member name="M:Loyc.Localize.From(Loyc.Symbol,System.String,System.Object[])">
<summary>
This is the heart of the Localize class, which localizes and formats a
string.
</summary>
<param name="resourceId">Resource ID used to look up a string. If
it is null then message must be provided; otherwise, message is only used
if no translation is available for the specified ID.</param>
<param name="message">The message to translate, which may include argument
placeholders (e.g. "{0}").</param>
<param name="args">Arguments given to Formatter to fill in placeholders
after the Localizer is called. If args is null or empty then Formatter
is not called.</param>
<returns>The translated and formatted string.</returns>
</member>
<member name="P:Loyc.Localize.Localizer">
<summary>Localizer method (thread-local)</summary>
</member>
<member name="P:Loyc.Localize.Formatter">
<summary>Formatting delegate (thread-local), which is set to
<see cref="M:Loyc.StringExt.Format(System.String,System.Object[])"/> by default.</summary>
</member>
<member name="T:Loyc.LocalizeExt">
<summary>Contains Localize() extension methods for strings.</summary>
<remarks>This would be part of the <see cref="M:Loyc.LocalizeExt.Localize(System.String,System.Object[])"/> class except that
the Localize class is not allowed to have a member that is also named
Localize.</remarks>
</member>
<member name="T:Loyc.LocalizableAttribute">
<summary>
I plan to use this attribute someday to gather all the localizable strings
in an application. This attribute should be applied to a string function
parameter if the method calls Localize() or Localize.From using that
parameter as the format string.
</summary>
</member>
<member name="T:Loyc.Math.Math128">
<summary>Contains methods for manipulating 128-bit numbers, multiplying
64-bit numbers to produce 128-bit results, and dividing 128-bit numbers
by 64-bit numbers.</summary>
<remarks>
MathEx.MulDiv and MathEx.MulShift rely on this class for 64x64 MulDiv()
and MulShift().
<para/>
Some functionality is incomplete at this time, e.g. there are no
comparison methods or 128+128 addition/subtraction.
<para/>
This class works on raw Int64 values, so a 128-bit number is represented
by a pair of Int64s, one with high bits and one with low bits. By
convention, the low 64 bits are always unsigned (because they contain no
sign bit), and the high 64 bits may be signed or unsigned, which
represents the sign of the 128-bit number as a whole.
<para/>
Many methods pass the low 64 bits by reference and the high 64 bits by
value, returning the "new" high 64 bits as the return value. This is done
to help implement signed math in terms of unsigned math. If the parameter
type is "ref ulong", C# does not allow you to pass "ref long", even with
a cast. Passing the high bits by value is therefore less cumbersome.
</remarks>
</member>
<member name="M:Loyc.Math.Math128.Divide(System.Int64,System.UInt64,System.Int64,System.Int64@,System.Boolean)">
<summary>Divides an signed 128-bit number by a signed 64-bit
number to produce a 64-bit result.</summary>
<returns>Returns the division result (known as the "quotient"). If the
result is too large to represent, long.MinValue or long.MaxValue is
returned instead.</returns>
<inheritdoc cref="M:Loyc.Math.Math128.Divide(System.Int64,System.UInt64,System.Int64,System.Int64@,System.Int64@,System.Boolean)"/>
</member>
<member name="M:Loyc.Math.Math128.Divide(System.Int64,System.UInt64,System.Int64,System.Int64@,System.Int64@,System.Boolean)">
<summary>Divides an signed 128-bit number by a signed 64-bit
number to produce a 128-bit result.</summary>
<param name="roundDown">If true, the result is rounded down, instead
of being rounded toward zero, which changes the remainder and
quotient if a is negative but b is positive.</param>
<remarks>
When dividing a negative number by a positive number, it is
conventionally rounded toward zero. Consequently, the remainder is zero
or negative to satisfy the standard integer division equation
<c>a = b*q + r</c>, where q is the quotient (result) and r is the
remainder.
<para/>
This is not always what you want. So, if roundDown is true, the result
is rounded down instead of toward zero. This ensures that if 'a' is
negative and 'b' is positive, the remainder is positive too, a fact
which is useful for modulus arithmetic. The table below illustrates
the difference:
<pre>
inputs | standard | roundDown
| output | output
a b | q r | q r
--- --- | --- --- | --- ---
7 3 | 2 1 | 2 1
-7 3 | -2 -1 | -3 2
7 -3 | -2 1 | -3 -2
-7 -3 | 2 -1 | 2 -1
</pre>
</remarks>
<inheritdoc cref="M:Loyc.Math.Math128.Divide(System.UInt64,System.UInt64,System.UInt64,System.UInt64@,System.UInt64@)"/>
</member>
<member name="M:Loyc.Math.Math128.Divide(System.UInt64,System.UInt64,System.UInt64,System.UInt64@)">
<summary>Divides an signed 128-bit number by a signed 64-bit
number to produce a 64-bit result.</summary>
<remarks>If the result did not fit in 64 bits, this method returns
ulong.MaxValue.</remarks>
<inheritdoc cref="M:Loyc.Math.Math128.Divide(System.UInt64,System.UInt64,System.UInt64,System.UInt64@,System.UInt64@)"/>
</member>
<member name="M:Loyc.Math.Math128.Divide(System.UInt64,System.UInt64,System.UInt64,System.UInt64@,System.UInt64@)">
<summary>Divides an unsigned 128-bit number by an unsigned 64-bit
number to produce a 128-bit result.</summary>
<param name="aH">High 64 bits of the dividend.</param>
<param name="aL">Low 64 bits of the dividend.</param>
<param name="b">The divisor.</param>
<param name="resultHi">High 64 bits of result.</param>
<param name="remainder">Remainder of the division.</param>
<returns>The low 64 bits of the result (known as the "quotient").</returns>
<exception cref="T:System.DivideByZeroException">b was zero.</exception>
</member>
<member name="M:Loyc.Math.Math128.ShiftLeft(System.UInt64,System.UInt64@,System.Int32)">
<summary>Shifts a 128-bit value left.</summary>
<param name="aH">High 64 bits</param>
<param name="aL">Low 64 bits</param>
<param name="amount">Number of bits to shift.</param>
<returns>The new value of aH</returns>
<remarks>The convention is that signed numbers use Int64 for aH and
unsigned numbers used UInt64 for aH. The fact that aH is not passed
by reference makes it easier to shift a signed number left by casting
aH to UInt64. The cast would not be allowed if passing by reference.
Of course, right shift, on the other hand, requires two separate
methods since it behaves differently for signed and unsigned inputs.
<para/>
This method does not allow shifting by a negative amount. The reason
is that there is only one ShiftLeft, so if the amount is negative,
it's not known whether a signed or unsigned ShiftRight is intended.
</remarks>
</member>
<member name="M:Loyc.Math.Math128.ShiftLeftFast(System.UInt64,System.UInt64@,System.Int32)">
<summary>Variation of ShiftLeft() for cases when you know 64 > amount >= 0.</summary>
</member>
<member name="M:Loyc.Math.Math128.ShiftLeftEx(System.UInt64@,System.UInt64@,System.Int32)">
<summary>Shifts a 128-bit value left and saves the overflowed bits.</summary>
<param name="aH">High 64 bits</param>
<param name="aL">Low 64 bits</param>
<param name="overflow">The bits shifted off the left of aH are <i>added
</i> to overflow. If overflow is an alias for aL, a left rotation
occurs.</param>
<param name="amount">Number of bits to shift. Negative amounts are not permitted.</param>
</member>
<member name="M:Loyc.Math.Math128.ShiftRight(System.UInt64,System.UInt64@,System.Int32)">
<summary>Shifts a 128-bit value right.</summary>
<param name="aH">High 64 bits</param>
<param name="aL">Low 64 bits</param>
<param name="amount">Number of bits to shift.</param>
<returns>The new value of aH</returns>
<remarks>This method, unlike ShiftLeft(), allows shifting by a negative
amount, which is translated to a left shift.
<para/>
TODO: ShiftRightEx</remarks>
</member>
<member name="M:Loyc.Math.Math128.ShiftRightFast(System.UInt64,System.UInt64@,System.Int32)">
<summary>Variation of ShiftRight() for cases when you know 64 > amount >= 0.</summary>
</member>
<!-- Badly formed XML comment ignored for member "M:Loyc.Math.Math128.ShiftRight(System.Int64,System.UInt64@,System.Int32)" -->
<member name="M:Loyc.Math.Math128.ShiftRightFast(System.Int64,System.UInt64@,System.Int32)">
<summary>Variation of ShiftRight() for cases when you know 64 > amount >= 0.</summary>
</member>
<member name="M:Loyc.Math.Math128.Add(System.UInt64,System.UInt64@,System.UInt64)">
<summary>Adds a 64-bit number to a 128-bit number.</summary>
<param name="aH">High 64 bits of 128-bit number</param>
<param name="aL">Low 64 bits of 128-bit number</param>
<param name="amount">Amount to add</param>
<returns>The high 64 bits of the result.</returns>
</member>
<member name="M:Loyc.Math.Math128.Subtract(System.UInt64,System.UInt64@,System.UInt64)">
<summary>Subtracts a 64-bit number from a 128-bit number.</summary>
<param name="aH">High 64 bits of 128-bit number</param>
<param name="aL">Low 64 bits of 128-bit number</param>
<param name="amount">Amount to subtract</param>
<returns>The high 64 bits of the result.</returns>
</member>
<member name="M:Loyc.Math.Math128.Add(System.Int64,System.UInt64@,System.Int64)">
<inheritdoc cref="M:Loyc.Math.Math128.Add(System.UInt64,System.UInt64@,System.UInt64)"/>
</member>
<member name="M:Loyc.Math.Math128.Subtract(System.Int64,System.UInt64@,System.Int64)">
<inheritdoc cref="M:Loyc.Math.Math128.Subtract(System.UInt64,System.UInt64@,System.UInt64)"/>
</member>
<member name="T:Loyc.Collections.Slice_`1">
<summary>A random-access range for a slice of an <see cref="T:Loyc.Collections.IListSource`1"/>.</summary>
<typeparam name="T">Item type in the list</typeparam>
<remarks>
This type was supposed to be called simply <c>Slice</c>, but this was not
allowed because in plain C#, "CS0542: member names cannot be the same as
their enclosing type" and of course, this type contains the Slice() method
from IListSource.
</remarks>
</member>
<member name="M:Loyc.Collections.Slice_`1.#ctor(Loyc.Collections.IListSource{`0},System.Int32,System.Int32)">
<summary>Initializes a slice.</summary>
<exception cref="T:System.ArgumentException">The start index was below zero.</exception>
<remarks>The (start, count) range is allowed to be invalid, as long
as 'start' and 'count' are zero or above.
<ul>
<li>If 'start' is above the original Count, the Count of the new slice
is set to zero.</li>
<li>if (start + count) is above the original Count, the Count of the new
slice is reduced to <c>list.Count - start</c>.</li>
</ul>
</remarks>
</member>
<member name="T:Loyc.Collections.ReversedListSource`1">
<summary>
Reversed view of IListSource returned from <see cref="M:Loyc.Collections.LCExt.ReverseView``1(Loyc.Collections.IListSource{``0})"/>
</summary>
</member>
<member name="T:Loyc.Collections.RangeEnumerator`1">
<summary>Enumerates through a forward range (<see cref="T:Loyc.Collections.IFRange`1"/>).</summary>
</member>
<member name="T:Loyc.Collections.RangeEnumerator`2">
<summary>Enumerates through a forward range (<see cref="T:Loyc.Collections.IFRange`1"/>),
calling the range methods through R instead of through <see cref="T:Loyc.Collections.IFRange`1"/>.
</summary>
<remarks>Although there is a ICloneable{R} constraint on R, it is currently
worthless due to a limitation of C#. Since <see cref="T:Loyc.Collections.IFRange`1"/> already
includes <see cref="!:ICloneable<IFRange<T>>"/>, this structure cannot simply
invoke Clone() directly because the compiler complains that Clone() is
ambiguous. Consequently it is necessary to cast the range to <see cref="T:Loyc.ICloneable`1"/> just to clone it; if R is a value type then it is
boxed, which defeats the entire performance advantage of calling
<c>ICloneable{R}.Clone()</c> instead of <c>ICloneable{IFRange{T}}.Clone</c>.
<para/>
Nevertheless, I have left the constraint in place, in the hope that EC# can
eventually eliminate this limitation thanks to its "using" cast. Once EC#
compiles directly to CIL, <c>range(using ICloneable<R>).Clone()</c> will
not perform boxing.
</remarks>
</member>
<member name="M:Loyc.Collections.LCExt.AsSource``1(System.Collections.Generic.ICollection{``0})">
<summary>Converts any ICollection{T} object to ISource{T}.</summary>
<remarks>This method is named "AsSource" and not "ToSource" because,
in contrast to methods like ToArray(), and ToList() it does not make a
copy of the sequence.</remarks>
</member>
<member name="M:Loyc.Collections.LCExt.AsCollection``1(System.Collections.Generic.IReadOnlyCollection{``0})">
<summary>Converts any ISource{T} object to a read-only ICollection{T}.</summary>
<remarks>This method is named "AsCollection" and not "ToCollection"
because, in contrast to methods like ToArray() and ToList(), it does not
make a copy of the sequence.</remarks>
</member>
<member name="M:Loyc.Collections.LCExt.AsListSource``1(System.Collections.Generic.IList{``0})">
<summary>Converts any IList{T} object to IListSource{T}.</summary>
<remarks>This method is named "AsListSource" and not "ToListSource"
because, in contrast to methods like ToArray() and ToList(), it does not
make a copy of the sequence.</remarks>
</member>
<member name="M:Loyc.Collections.LCExt.AsList``1(Loyc.Collections.IListSource{``0})">
<summary>Converts any IListSource{T} object to a read-only IList{T}.</summary>
<remarks>This method is named "AsList" and not "ToList" because
because, in contrast to methods like ToArray(), it does not make a copy
of the sequence.</remarks>
</member>
<member name="M:Loyc.Collections.LCExt.NegView``1(Loyc.Collections.IListSource{``0},System.Int32)">
<inheritdoc cref="M:Loyc.Collections.NegListSource`1.#ctor(Loyc.Collections.IListSource{`0},System.Int32)"/>
</member>
<member name="M:Loyc.Collections.LCExt.NegView``1(System.Collections.Generic.IList{``0},System.Int32)">
<inheritdoc cref="M:Loyc.Collections.NegList`1.#ctor(System.Collections.Generic.IList{`0},System.Int32)"/>
</member>
<member name="T:Loyc.Collections.DictionaryExt">
<summary>Extension methods for <see cref="T:System.Collections.Generic.Dictionary`2"/> and <see cref="T:System.Collections.Generic.IDictionary`2"/>.</summary>
</member>
<member name="M:Loyc.Collections.DictionaryExt.TryGetValue``2(System.Collections.Generic.Dictionary{``0,``1},``0,``1)">
<summary>An alternate version TryGetValue that returns a default value
if the key was not found in the dictionary, and that does not throw if
the key is null.</summary>
<returns>The value associated with the specified key, or defaultValue
if no value is associated with the key.</returns>
</member>
<member name="M:Loyc.Collections.DictionaryExt.TryGetValue``2(System.Collections.Generic.IDictionary{``0,``1},``0,``1)">
<inheritdoc cref="M:Loyc.Collections.DictionaryExt.TryGetValue``2(System.Collections.Generic.Dictionary{``0,``1},``0,``1)"/>
</member>
<member name="T:Loyc.Collections.INegListSource`1">
<summary>This interface is the counterpart to <see cref="T:Loyc.Collections.IListSource`1"/>
for lists whose minimum index is not (necessarily) zero.</summary>
<remarks>
Be careful not to write a loop that relies on <see cref="P:Loyc.Collections.ICount.Count"/> or starts at
zero! You must always loop from Min to Max, like so:
<code>
for (int i = list.Min; i <= list.Max; i++) { ... }
</code>
</remarks>
</member>
<member name="M:Loyc.Collections.INegListSource`1.TryGet(System.Int32,System.Boolean@)">
<summary>Gets the item at the specified index, and does not throw an
exception on failure.</summary>
<param name="index">An index in the range Min to Max.</param>
<param name="fail">A flag that is set on failure. To improve
performance slightly, this flag is not cleared on success.</param>
<returns>The element at the specified index, or default(T) if the index
is not valid.</returns>
<remarks>In my original design, the caller could provide a value to
return on failure, but this would not allow T to be marked as "out" in
C# 4. For the same reason, we cannot have a ref/out T parameter.
Instead, the following extension methods are provided:
<code>
bool TryGet(int index, ref T value);
T TryGet(int, T defaultValue);
</code>
</remarks>
</member>
<member name="P:Loyc.Collections.INegListSource`1.Min">
<summary>Returns the minimum valid index in the collection.</summary>
</member>
<member name="P:Loyc.Collections.INegListSource`1.Max">
<summary>Returns the maximum valid index in the collection.</summary>
<remarks><see cref="P:Loyc.Collections.ICount.Count"/> must equal Max-Min+1.</remarks>
</member>
<member name="P:Loyc.Collections.INegListSource`1.Item(System.Int32)">
<summary>Gets the item at the specified index.</summary>
<param name="index">An index in the range Min to Max.</param>
<exception cref="T:System.ArgumentOutOfRangeException">The index provided is not
valid in this list.</exception>
<returns>The element at the specified index.</returns>
</member>
<member name="T:Loyc.Collections.LCInterfaces">
<summary>
This class contains extension methods that are provided as part of various
Loyc.Collections interfaces. For example, it provides methods such as IndexOf(),
Contains() and CopyTo(), that the traditional <see cref="T:System.Collections.Generic.ICollection`1"/>
and <see cref="T:System.Collections.Generic.IList`1"/> interfaces require the author to write himself.
</summary>
<remarks>
For covariant collections such as <see cref="!:ISource<T>"/> and <see cref="T:Loyc.Collections.IListSource`1"/>, the CLR actually prohibits methods such as
Contains(T) and IndexOf(T), because T is not allowed in "input" positions.
Therefore, these extension methods must be used to fill the gap. Even
methods such as <i>bool TryGet(int, out T)</i> are prohibited, so TryGet()
has the signature <i>T TryGet(ref bool failed)</i> instead, and extension
methods provide the original version of the method in addition.
</remarks>
<summary>Contains <see cref="!:GetIterator"/>, which makes an iterator for
a portion of a list.</summary>
</member>
<member name="M:Loyc.Collections.LCInterfaces.TryGet``1(Loyc.Collections.INegListSource{``0},System.Int32,``0@)">
<summary>Tries to get a value from the list at the specified index.</summary>
<param name="index">The index to access. Valid indexes are between Min and Max.</param>
<param name="value">A variable that will be changed to the retrieved value. If the index is not valid, this variable is left unmodified.</param>
<returns>True on success, or false if the index was not valid.</returns>
</member>
<member name="M:Loyc.Collections.LCInterfaces.TryGet``1(Loyc.Collections.INegListSource{``0},System.Int32,``0)">
<summary>Tries to get a value from the list at the specified index.</summary>
<param name="index">The index to access. Valid indexes are between Min and Max.</param>
<param name="defaultValue">A value to return if the index is not valid.</param>
<returns>The retrieved value, or defaultValue if the index provided was not valid.</returns>
</member>
<member name="M:Loyc.Collections.LCInterfaces.IndexOf``1(Loyc.Collections.INegListSource{``0},``0)">
<summary>Determines the index of a specific value.</summary>
<returns>The index of the value, if found, or -1 if it was not found.</returns>
<remarks>
At first, this method was a member of IListSource itself, just in
case the source might have some kind of fast lookup logic (e.g. binary
search) or custom comparer. However, since the item to find is an "in"
argument, it would prevent IListSource from being marked covariant when
I upgrade to C# 4.
</remarks>
</member>
<member name="M:Loyc.Collections.LCInterfaces.Any(Loyc.Collections.ICount)">
<summary>Returns true if the collection contains any elements.</summary>
</member>
<member name="M:Loyc.Collections.LCInterfaces.TryGet``1(Loyc.Collections.IListSource{``0},System.Int32,``0@)">
<summary>Tries to get a value from the list at the specified index.</summary>
<param name="index">The index to access. Valid indexes are between 0 and Count-1.</param>
<param name="value">A variable that will be changed to the retrieved value. If the index is not valid, this variable is left unmodified.</param>
<returns>True on success, or false if the index was not valid.</returns>
</member>
<member name="M:Loyc.Collections.LCInterfaces.TryGet``1(Loyc.Collections.IListSource{``0},System.Int32,``0)">
<summary>Tries to get a value from the list at the specified index.</summary>
<param name="index">The index to access. Valid indexes are between 0 and Count-1.</param>
<param name="defaultValue">A value to return if the index is not valid.</param>
<returns>The retrieved value, or defaultValue if the index provided was not valid.</returns>
</member>
<member name="M:Loyc.Collections.LCInterfaces.IndexOf``1(Loyc.Collections.IListSource{``0},``0)">
<summary>Determines the index of a specific value.</summary>
<returns>The index of the value, if found, or -1 if it was not found.</returns>
<remarks>
At first, this method was a member of IListSource itself, just in
case the source might have some kind of fast lookup logic (e.g. binary
search) or custom comparer. However, since the item to find is an "in"
argument, it would prevent IListSource from being marked covariant when
I upgrade to C# 4.
</remarks>
</member>
<member name="M:Loyc.Collections.LCInterfaces.IndexWhere``1(Loyc.Collections.IListSource{``0},System.Func{``0,System.Boolean})">
<summary>Gets the lowest index at which a condition is true, or -1 if nowhere.</summary>
</member>
<member name="M:Loyc.Collections.LCInterfaces.LastIndexWhere``1(Loyc.Collections.IListSource{``0},System.Func{``0,System.Boolean})">
<summary>Gets the highest index at which a condition is true, or -1 if nowhere.</summary>
</member>
<member name="M:Loyc.Collections.LCInterfaces.ToArray``1(Loyc.Collections.IListSource{``0})">
<summary>Copies the contents of an IListSource to an array.</summary>
</member>
<member name="T:Loyc.Collections.INegArray`1">
<summary>This interface models the capabilities of an array: getting and
setting elements by index, but not adding or removing elements. This
interface is the counterpart to <see cref="T:Loyc.Collections.IListSource`1"/>
for lists whose minimum index is not (necessarily) zero.
</summary>
</member>
<member name="P:Loyc.Collections.INegArray`1.Item(System.Int32)">
<summary>Gets or sets an element of the array-like collection.</summary>
<returns>The value of the array at the specified index.</returns>
<remarks>
A redundant getter is required by C# because C# code is unable to use it
(from a reference to <see cref="T:Loyc.Collections.INegArray`1"/>) otherwise.
</remarks>
</member>
<member name="T:Loyc.Collections.INegAutoSizeArray`1">
<summary>An auto-sizing array is a list structure that allows you to modify
the element at any index, including indexes that don't yet exist; the
collection automatically adds missing indexes.</summary>
<typeparam name="T">Data type of each element.</typeparam>
<remarks>
This interface allows negative indexes, unlike <see cref="T:Loyc.Collections.IAutoSizeArray`1"/>.
</remarks>
</member>
<member name="M:Loyc.Collections.INegAutoSizeArray`1.Optimize">
<summary>Optimizes the data structure to consume less memory or storage space.</summary>
<remarks>
A simple auto-sizing array can implement this method by examining the
elements with the most positive and most negative indexes, and removing
any that are equal to default(T).
</remarks>
</member>
<member name="T:Loyc.Collections.INegDeque`1">
<summary>Represents a Deque that supports negative indexes. In this kind of
Deque, pushing and popping elements does not affect the indexes of the other
elements in the collection.</summary>
<typeparam name="T"></typeparam>
</member>
<member name="T:Loyc.Collections.IDeque`1">
<summary>Represents a double-ended queue that allows items to be added or
removed at the beginning or end.</summary>
<typeparam name="T">Type of each element</typeparam>
</member>
<member name="P:Loyc.Collections.IDeque`1.First">
<summary>Gets the first item in the deque.</summary>
<exception cref="T:System.InvalidOperationException"></exception>
</member>
<member name="T:Loyc.Collections.WeakValueDictionary`2">
<summary>
A dictionary in which the values are weak. When a value has been garbage-
collected, the dictionary acts as if the key is not present (except the
Remove() method, which saves time by not checking whether the value is
dead.)
</summary>
<remarks>
This is implemented on top of a standard Dictionary. In order to allow the
dictionary to be read safely while it is being enumerated, cleanup
operations (to remove entries whose value has been garbage-collected) do
not occur automatically during read operations. You can allow cleanups
by calling AutoCleanup().
</remarks>
</member>
<member name="M:Loyc.Collections.WeakValueDictionary`2.AutoCleanup">
<summary>Periodically removes entries with garbage-collected values from the dictionary</summary>
</member>
<member name="M:Loyc.Collections.WeakValueDictionary`2.Cleanup">
<summary>Removes entries with garbage-collected values from the dictionary.</summary>
</member>
<member name="P:Loyc.Collections.WeakValueDictionary`2.Count">
<summary>Returns the number of dictionary entries. This value may be
greater than the number of elements that are still alive.</summary>
</member>
<member name="M:Loyc.StringExt.SplitAt(System.String,System.Char)">
<summary>Splits a string in two pieces.</summary>
<param name="s">String to split</param>
<param name="c">Dividing character.</param>
<returns>Returns the string to the left and to the right of the
first occurance of 'c' in the string, not including 'c' itself.
If 'c' was not found in 's', the pair (s, null) is returned.</returns>
</member>
<member name="M:Loyc.StringExt.Right(System.String,System.Int32)">
<summary>Returns the rightmost 'count' characters of 's', or s itself if count > s.Length.</summary>
</member>
<member name="M:Loyc.StringExt.Left(System.String,System.Int32)">
<summary>Returns the leftmost 'count' characters of 's', or s itself if count > s.Length.</summary>
</member>
<member name="M:Loyc.StringExt.Join(System.String,System.Collections.IEnumerable)">
<summary>Converts a series of values to strings, and concatenates them
with a given separator between them.</summary>
<example>Join(" + ", new[] { 1,2,3 }) returns "1 + 2 + 3".</example>
</member>
<member name="M:Loyc.StringExt.Join(System.String,System.Collections.IEnumerator)">
<inheritdoc cref="M:Loyc.StringExt.Join(System.String,System.Collections.IEnumerable)"/>
</member>
<member name="M:Loyc.StringExt.Format(System.String,System.Object[])">
<summary>
This formatter works like string.Format, except that named
placeholders accepted as well as numeric placeholders. This method
replaces named placeholders with numbers, then calls string.Format.
</summary>
<remarks>
Named placeholders are useful for communicating information about a
placeholder to a human translator. Here is an example:
<code>
Not enough memory to {load/parse} '{filename}'.
</code>
In some cases a translator might have difficulty translating a phrase
without knowing what a numeric placeholder ({0} or {1}) refers to, so
a named placeholder can provide an important clue. The localization
system is invoked as follows:
<code>
string msg = Localize.From("{man's name} meets {woman's name}.",
"man's name", mansName, "woman's name", womansName);
</code>
The placeholder names are not case sensitive.
You can use numeric placeholders, alignment and formatting codes also:
<code>
string msg = Localize.From("You need to run {km,6:###.00} km to reach {0}",
cityName, "KM", 2.9);
</code>
This method will ignore the first N+1 arguments in args, where {N}
is the largest numeric placeholder. It is assumed that the placeholder
name ends at the first comma or colon; hence the placeholder in this
example is called "km", not "km,6:###.00".
If a placeholder name is not found in the argument list then it is not
replaced with a number before the call to string.Format, so a
FormatException will occur.
</remarks>
</member>
<member name="M:Loyc.StringExt.EliminateNamedArgs(System.String,System.Object[])">
<summary>Called by Format to replace named placeholders with numeric
placeholders in format strings.</summary>
<returns>A format string that can be used to call string.Format.</returns>
<seealso cref="M:Loyc.StringExt.Format(System.String,System.Object[])"/>
</member>
<member name="T:Loyc.Math.BoundingBox`1">
<summary>Holds a mutable 2D bounding rectangle.</summary>
<typeparam name="T">Data type of each coordinate.</typeparam>
<remarks>Several extension methods are provided in <see cref="!:BoundingBoxExt"/>.</remarks>
</member>
<member name="T:Loyc.Math.IRectangle`1">
<summary>Represents a mutable 2D rectangle.</summary>
<remarks>
This interface is separated into two bases,
<see cref="T:Loyc.Math.IRectangleBase`1"/> and <see cref="T:Loyc.Math.INewRectangle`2"/>,
for the same reason that <see cref="T:Loyc.Math.IPoint`1"/>'s coordinates are
divided into <see cref="T:Loyc.Math.IPointBase`1"/> and <see cref="T:Loyc.Math.INewPoint`2"/>,
as explained in the documentation of <see cref="T:Loyc.Math.IPoint`1"/>.
</remarks>
</member>
<member name="T:Loyc.Math.INewRectangle`2">
<summary>This interface exists to work around a limitation of C#; see
<see cref="T:Loyc.Math.IRectangle`1"/>.</summary>
</member>
<member name="T:Loyc.Collections.Impl.InternalList`1">
<summary>A compact auto-enlarging array structure that is intended to be
used within other data structures. It should only be used internally in
"private" or "protected" members of low-level code.
</summary>
<remarks>
InternalList is a struct, not a class, in order to save memory; and for
maximum performance, it asserts rather than throwing an exception
when an incorrect array index is used. Besides that, it has an
InternalArray property that provides access to the internal array.
For all these reasons one should not expose it in a public API, and
it should only be used when performance trumps all other concerns.
<para/>
Passing this structure by value is dangerous because changes to a copy
of the structure may or may not be reflected in the original list. It's
best not to pass it around at all, but if you must pass it, pass it by
reference.
<para/>
Also, do not use the default contructor. Always specify an initial
capacity or copy InternalList.Empty so that _array gets a value.
This is required because methods such as Add(), Insert() and Resize()
assume _array is not null.
<para/>
InternalList has one nice thing that List(of T) lacks: a <see cref="M:Loyc.Collections.Impl.InternalList`1.Resize(System.Int32,System.Boolean)"/>
method and an equivalent Count setter. Which dork at Microsoft decided no
one should be allowed to set the list length directly? This type also
provides a handy <see cref="P:Loyc.Collections.Impl.InternalList`1.Last"/> property and a <see cref="M:Loyc.Collections.Impl.InternalList`1.Pop"/>
method to respectively get or remove the last item.
<para/>
Finally, alongside InternalList(T), the static class InternalList comes
with some static methods (CopyToNewArray, Insert, RemoveAt, Move) to help
manage raw arrays. You might want to use these in a data structure
implementation even if you choose not to use InternalList(T) instances.
</remarks>
</member>
<member name="T:Loyc.Collections.IListRangeMethods`1">
<summary>An interface typically implemented alongside <see cref="T:System.Collections.Generic.IList`1"/>
for collection types that can add or remove multiple items in one method
call, and sort all or part of the list.</summary>
<remarks>
This interface comes with extension methods <see cref="M:Loyc.Collections.LCInterfaces.Resize``1(Loyc.Collections.IListRangeMethods{``0},System.Int32)"/>
and <see cref="M:Loyc.Collections.LCInterfaces.Sort``1(Loyc.Collections.IListRangeMethods{``0})"/>.
</remarks>
</member>
<member name="M:Loyc.Collections.IListRangeMethods`1.Sort(System.Int32,System.Int32,System.Comparison{`0})">
<summary>Sorts all or part of the list.</summary>
<param name="index">Index of the beginning of the range of items to sort</param>
<param name="count">Width of the range of items to sort</param>
<param name="comp">Comparison method that establishes the sort order</param>
<remarks>
Extension methods are also provided for sorting, so that you need not
provide all three parameters.
</remarks>
</member>
<member name="M:Loyc.Collections.Impl.InternalList`1.Resize(System.Int32,System.Boolean)">
<summary>Makes the list larger or smaller, depending on whether
<c>newSize</c> is larger or smaller than <see cref="P:Loyc.Collections.Impl.InternalList`1.Count"/>.</summary>
<param name="allowReduceCapacity">If this is true, and the new size is
smaller than one quarter the current <see cref="P:Loyc.Collections.Impl.InternalList`1.Capacity"/>, the array
is reallocated to a smaller size. If this parameter is false, the array
is never reallocated when shrinking the list.</param>
<param name="newSize">New value of <see cref="P:Loyc.Collections.Impl.InternalList`1.Count"/>. If the Count
increases, copies of default(T) are added to the end of the the list;
otherwise items are removed from the end of the list.</param>
</member>
<member name="M:Loyc.Collections.Impl.InternalList`1.Clear">
<summary>Clears the list and frees the memory used by the list. Can
also be used to initialize a list whose constructor was never called.</summary>
</member>
<member name="M:Loyc.Collections.Impl.InternalList`1.Clone">
<summary>Makes a copy of the list with the same capacity</summary>
</member>
<member name="M:Loyc.Collections.Impl.InternalList`1.CloneAndTrim">
<summary>Makes a copy of the list with Capacity = Count</summary>
</member>
<member name="M:Loyc.Collections.Impl.InternalList`1.ToArray">
<summary>Makes a copy of the list, as an array</summary>
</member>
<member name="M:Loyc.Collections.Impl.InternalList`1.Move(System.Int32,System.Int32)">
<summary>Slides the array entry at [from] forward or backward in the
list, until it reaches [to].</summary>
<remarks>
For example, if a list of integers is [0, 1, 2, 3, 4, 5] then Move(4,1)
produces the following result: [0, 4, 1, 2, 3, 5].
</remarks>
</member>
<member name="P:Loyc.Collections.Impl.InternalList`1.Capacity">
<summary>Gets or sets the array length.</summary>
<remarks>Changing this property requires O(Count) time and temporary
space. Attempting to set the capacity lower than Count has no effect.
</remarks>
</member>
<member name="T:Loyc.Collections.Impl.InternalList">
<summary>
Contains static methods to help manage raw arrays with even less
overhead than <see cref="T:Loyc.Collections.Impl.InternalList`1"/>.
</summary>
<remarks>
The methods of this class are used by some data structures that contain
arrays but, for whatever reason, don't use <see cref="T:Loyc.Collections.Impl.InternalList`1"/>.
These methods are also used by InternalList(T) itself.
</remarks>
</member>
<member name="M:Loyc.Collections.Impl.InternalList.BinarySearch``2(``0[],System.Int32,``1,System.Func{``0,``1,System.Int32},System.Boolean)">
<summary>Performs a binary search with a custom comparison function.</summary>
<param name="_array">Array to search</param>
<param name="_count">Number of elements used in the array</param>
<param name="k">A key to compare with elements of the array</param>
<param name="compare">Lambda function that knows how to compare Ts with
Ks (T and K can be the same). It is passed a series of elements from
the array. It must return 0 if the element has the desired value, 1 if
the supplied element is higher than desired, and -1 if it is lower than
desired.</param>
<param name="lowerBound">Whether to find the "lower bound" in case there
are duplicates in the list. If duplicates exist of the search key k
exist, the lowest index of a matching duplicate is returned. This
search mode may be slightly slower when a match exists.</param>
<returns>The index of the matching array entry, if found. If no exact
match was found, this method returns the bitwise complement of an
insertion location that would preserve the order.</returns>
<example>
// The first 6 elements are sorted. The seventh is invalid,
// and must be excluded from the binary search.
int[] array = new int[] { 0, 10, 20, 30, 40, 50, -1 };
// The result will be 2, because array[2] == 20.
int a = InternalList.BinarySearch(array, 6, i => i.CompareTo(20));
// The result will be ~2, which equals -3, because index 2 would
// be the correct place to insert 17 to preserve the sort order.
int b = InternalList.BinarySearch(array, 6, i => i.CompareTo(17));
</example>
</member>
<member name="M:Loyc.Collections.Impl.InternalList.BinarySearchByIndex``1(``0,System.Int32,System.Func{System.Int32,``0,System.Int32},System.Boolean)">
<summary>A binary search function that knows nothing about the list
being searched.</summary>
<typeparam name="Anything">Any data type relevant to the caller.</typeparam>
<param name="data">State information to be passed to compare()</param>
<param name="count">Number of items in the list being searched</param>
<param name="compare">Comparison method that is given the current index
to examine and the state parameter "data".</param>
<param name="lowerBound">Whether to find the "lower bound" in case there
are duplicates in the list. If duplicates exist of the search key k
exist, the lowest index of a matching duplicate is returned. This
search mode may be slightly slower when a match exists.</param>
<returns>The index of the matching index, if found. If no exact
match was found, this method returns the bitwise complement of an
insertion location that would preserve the sort order.</returns>
</member>
<member name="M:Loyc.Collections.Impl.InternalList.NextLargerSize(System.Int32)">
<summary>As an alternative to the typical enlarging pattern of doubling
the array size when it overflows, this function proposes a 75% size
increase instead (100% when the array is small), while ensuring that
the array length stays even.</summary>
<remarks>
With a seed of 0, 2, or 4: 0, 2, 4, 8, 16, 30, 54, 96, 170, 298, 522...<br/>
With a seed of 1: 1, 2, 4, 8, 16, 30, 54, 96, 170, 298, 522...<br/>
With a seed of 3: 3, 6, 12, 22, 40, 72, 128, 226, 396...<br/>
With a seed of 5: 5, 10, 18, 32, 58, 102, 180, 316, 554...<br/>
With a seed of 7: 7, 14, 26, 46, 82, 144, 254, 446, 782...
<para/>
75% size increases require 23.9% more allocations than size doubling
(1.75 to the 1.239th power is about 2.0), but memory utilization is
increased. With size doubling, the average list uses 2/3 of its
entries, but with this resizing pattern, the average list uses 72.72%
of its entries. The average size of a list is 8.3% lower. Originally
I used 50% size increases, but they required 71% more allocations,
which seemed like too much.
</remarks>
</member>
<member name="M:Loyc.Collections.Impl.InternalList.NextLargerSize(System.Int32,System.Int32)">
<summary>Same as <see cref="M:Loyc.Collections.Impl.InternalList.NextLargerSize(System.Int32)"/>, but allows you to
specify a capacity limit, to avoid wasting memory when a collection has
a known maximum size.</summary>
<param name="than">Return value will be larger than this number.</param>
<param name="capacityLimit">Maximum value to return. This parameter is
ignored if it than >= capacityLimit.</param>
<returns>Produces the same result as <see cref="M:Loyc.Collections.Impl.InternalList.NextLargerSize(System.Int32)"/>
unless the return value would be near capacityLimit (and capacityLimit
> than). If the return value would be more than capacityLimit,
capacityLimit is returned instead. If the return value would be slightly
less than capacityLimit (within 20%) then capacityLimit is returned,
to ensure that another reallocation will not be required later.</returns>
</member>
<member name="M:Loyc.Collections.Impl.InternalList.Sort``1(``0[],System.Int32,System.Int32,System.Comparison{``0})">
<summary>Performs a quicksort using a Comparison function.</summary>
<remarks>
Normally one uses Array.Sort for sorting arrays.
This method exists because there is no Array.Sort overload that
accepts both a Comparison and a range (index, count), nor does the
.NET framework provide access to its internal adapter that converts
Comparison to IComparer.
</remarks>
</member>
<member name="M:Loyc.Collections.Impl.InternalList.InsertionSort``1(``0[],System.Int32,System.Int32,System.Comparison{``0})">
<summary>Performs an insertion sort.</summary>
<remarks>The insertion sort is a stable sort algorithm that is slow in
general (O(N^2)). It should be used only when (a) the list to be sorted
is short (less than about 20 elements) or (b) the list is very nearly
sorted already.</remarks>
<seealso cref="M:Loyc.Collections.ListExt.InsertionSort``1(System.Collections.Generic.IList{``0},System.Int32,System.Int32,System.Comparison{``0})"/>
</member>
<member name="T:Loyc.Collections.StringSlice">
<summary>A random-access slice of System.String.</summary>
<remarks>
Where possible, it is recommended that you use <see cref="T:Loyc.UString"/> instead.
</remarks>
</member>
<member name="M:Loyc.Collections.StringSlice.#ctor(System.String,System.Int32,System.Int32)">
<summary>Initializes a StringSlice.</summary>
<exception cref="T:System.ArgumentException">The start index was below zero.</exception>
<remarks>The (start, count) range is allowed to be invalid, as long
as 'start' is zero or above.
<ul>
<li>If 'count' is below zero, or if 'start' is above the original Length,
the Count of the new slice is set to zero.</li>
<li>if (start + count) is above the original Length, the Count of the new
slice is reduced to <c>list.Length - start</c>.</li>
</ul>
</remarks>
</member>
<member name="T:Loyc.Collections.ListAsListSource`1">
<summary>
Helper type returned from <see cref="M:Loyc.Collections.LCExt.AsListSource``1(System.Collections.Generic.IList{``0})"/>.
</summary>
<summary>A read-only wrapper that implements ICollection and ISource.</summary>
</member>
<member name="T:Loyc.Collections.IPush`1">
<summary>Represents a collection that accepts a sequence of items.</summary>
</member>
<member name="T:Loyc.Collections.IPop`1">
<summary>Represents a collection that produces a sequence of items, and can
return the next item without popping it (the Peek operation).</summary>
<remarks>Push/Pop methods that throw an exception on failure, and
TryPush/TryPop methods that don't require a "ref" argument, are
available as extension methods.</remarks>
</member>
<member name="T:Loyc.Collections.IQueue`1">
<summary>Represents a FIFO (first-in-first-out) queue.</summary>
<typeparam name="T">Type of each element</typeparam>
</member>
<member name="T:Loyc.Collections.IStack`1">
<summary>Represents a LIFO (last-in-first-out) stack.</summary>
<typeparam name="T">Type of each element</typeparam>
</member>
<!-- Badly formed XML comment ignored for member "T:Loyc.Collections.WeakKeyComparer`1" -->
<member name="T:Loyc.Collections.WeakKeyReference`1">
<summary>Provides a weak reference to an object of the given type to be used
in a WeakDictionary along with the given comparer.</summary>
<remarks>Source: datavault project. License: Apache License 2.0</remarks>
</member>
<member name="T:Loyc.Collections.IMFRange`1">
<summary>A mutable forward range.</summary>
<remarks>
This range lets you change the value of <see cref="!:First"/>.
<para/>
Please see <see cref="T:Loyc.Collections.IFRange`1"/> for general documentation about ranges.
<para/>
The mutable ranges do not include a clone method due to a limitation of C#.
C# does not support covariance, which means that every time a derived
interface supports cloning, the implementing class is required to write a
separate clone method. Read-only ranges already have to implement up to
four clone methods: ICloneable{IFRange{T}}, ICloneable{IBRange{T}},
ICloneable{IRange{T}}, and ICloneable{IRangeEx{T}}, and that's in addition
to the Clone method for the concrete type! If mutable ranges also supported
cloning, they would add up to three more clone methods, which is really
getting out of hand.
<para/>
To limit the maximum number of clone methods to something reasonable, only
the immutable ranges have a clone method, but if the original range was
mutable then the clone will also be mutable; you just have to cast the
result:
<code>
var r2 = (IMFRange<T>)r.Clone();
</code>
</remarks>
</member>
<member name="P:Loyc.Collections.IMFRange`1.Front">
<summary>Gets or sets the value of the first item in the range.</summary>
<exception cref="T:Loyc.Collections.EmptySequenceException">The sequence is empty.</exception>
</member>
<member name="T:Loyc.Collections.IMBRange`1">
<summary>A mutable bidirectional range.</summary>
<remarks>This range lets you change the value of <see cref="!:First"/> and <see cref="!:Last"/>.
<para/>
Please see <see cref="T:Loyc.Collections.IFRange`1"/> for general documentation about ranges.
</remarks>
</member>
<member name="P:Loyc.Collections.IMBRange`1.Back">
<summary>Gets or sets the value of the last item in the range.</summary>
<exception cref="T:Loyc.Collections.EmptySequenceException">The sequence is empty.</exception>
</member>
<member name="T:Loyc.Collections.IBRangeEx`2">
<summary>A bidirectional range that can perform operations such as
intersection and overlap tests on pairs of ranges of the same type.</summary>
<typeparam name="R">The type that implements this interface</typeparam>
</member>
<member name="M:Loyc.Collections.IBRangeEx`2.Intersect(`0)">
<summary>Gets the region of overlap between two ranges.</summary>
<remarks>If the ranges do not overlap, an empty range is returned with
<see cref="P:Loyc.Collections.IBRangeEx`2.InnerList"/> set to the same value that this range has.</remarks>
</member>
<member name="M:Loyc.Collections.IBRangeEx`2.Union(`0)">
<summary>Gets a range just large enough to contain both ranges.</summary>
<exception cref="T:System.InvalidOperationException">The two ranges cannot be
combined because they have different <see cref="P:Loyc.Collections.IBRangeEx`2.InnerList"/> values.</exception>
<remarks>As long as both ranges are based on the same list, this method
succeeds. For example, if one range covers 5..6 and the other range
covers 10..20, the union covers 5..20.</remarks>
</member>
<member name="P:Loyc.Collections.IBRangeEx`2.InnerList">
<summary>Gets the list upon which this range is based.</summary>
<remarks>The return type is <see cref="T:System.Collections.Generic.IEnumerable`1"/> since the
actual list type could vary, e.g. it might be <see cref="T:System.Collections.Generic.ICollection`1"/>
or <see cref="T:Loyc.Collections.IListSource`1"/>.</remarks>
</member>
<member name="P:Loyc.Collections.IBRangeEx`2.SliceStart">
<summary>Index where this range starts within the <see cref="P:Loyc.Collections.IBRangeEx`2.InnerList"/>.</summary>
</member>
<member name="T:Loyc.Collections.IBRangeEx`1">
<summary>A bidirectional range that can perform operations such as
intersection and overlap tests on pairs of ranges.</summary>
</member>
<member name="T:Loyc.Collections.IRangeEx`2">
<summary>A random-access range that can perform operations such as
intersection and overlap tests on pairs of ranges of the same type.</summary>
</member>
<member name="T:Loyc.Collections.IRangeEx`1">
<summary>A random-access range that can perform operations such as
intersection and overlap tests on pairs of ranges.</summary>
</member>
<member name="T:Loyc.Collections.IMRange`1">
<summary>A mutable random-access range.</summary>
<remarks>IMRange models a shrinkable array. You can modify elements or
shrink the array, but not add anything new; this is a useful interface
for some divide-and-conquer problems, such as the quick sort.
<para/>
Please see <see cref="T:Loyc.Collections.IFRange`1"/> for general documentation about ranges.
</remarks>
</member>
<member name="T:Loyc.Collections.NegList`1">
<summary>
Provides a view of an <see cref="T:System.Collections.Generic.IList`1"/> in which the Count is the same, but the
minimum index is not necessarily zero. Returned from <see cref="M:Loyc.Collections.LCExt.NegView``1(System.Collections.Generic.IList{``0},System.Int32)"/>.
</summary>
<remarks>This wrapper is a structure in order to offer high performance in
certain scenarios.</remarks>
</member>
<member name="M:Loyc.Collections.NegList`1.#ctor(System.Collections.Generic.IList{`0},System.Int32)">
<summary>Initializes a NegListSource wrapper.</summary>
<param name="list">A list to wrap (must not be null).</param>
<param name="zeroOffset">An index into the original list. this[0] will refer to that index.</param>
<remarks>The zeroOffset can be any integer, but if it is not in the range 0 to list.Count-1, this[0] will not be valid.</remarks>
</member>
<member name="M:Loyc.Collections.NegList`1.TryGet(System.Int32,System.Boolean@)">
<inheritdoc/>
</member>
<member name="M:Loyc.Collections.NegList`1.TrySet(System.Int32,`0)">
<inheritdoc/>
</member>
<member name="M:Loyc.Collections.NegList`1.Equals(System.Object)">
<inheritdoc cref="!:Loyc.Essentials.WrapperBase<T>.Equals"/>
</member>
<member name="M:Loyc.Collections.NegList`1.ToString">
<summary>Returns ToString() of the wrapped list.</summary>
</member>
<member name="P:Loyc.Collections.NegList`1.OriginalList">
<summary>Gets the list that was passed to the constructor of this instance.</summary>
</member>
<member name="P:Loyc.Collections.NegList`1.Offset">
<summary>Returns the offset added to indexes in the original list, which equals -Min.</summary>
<remarks>The 0th item in this list the same as OriginalList[Offset].</remarks>
<remarks>
WARNING: this is a value type. Calling the setter may have unexpected
consequences for people unfamiliar with the .NET type system, because
it is easy to make copies accidentally, and changing the Offset in a copy
does not change the Offset in the original.
</remarks>
</member>
<member name="P:Loyc.Collections.NegList`1.Count">
<summary>Returns the total number of items in the list (same as OriginalList.Count).</summary>
</member>
<member name="P:Loyc.Collections.NegList`1.Min">
<summary>Returns the minimum valid index.</summary>
</member>
<member name="P:Loyc.Collections.NegList`1.Max">
<summary>Returns the maximum valid index, which is Min + OriginalList.Count - 1.</summary>
</member>
<member name="P:Loyc.Collections.NegList`1.Item(System.Int32)">
<summary>Gets the value of the list at the specified index. In terms
of the original list, this is OriginalList[index + Offset]</summary>
<param name="index">An index in the range Min to Max.</param>
<exception cref="T:System.ArgumentOutOfRangeException">The index provided is not
valid in this list.</exception>
</member>
<member name="T:Loyc.Collections.CollectionAsSource`1">
<summary>A read-only wrapper that implements ICollection(T) and ISource(T),
returned from <see cref="M:Loyc.Collections.LCExt.AsSource``1(System.Collections.Generic.ICollection{``0})"/>.</summary>
</member>
<member name="T:Loyc.Threading.ThreadEx">
<summary>Creates and controls a thread, and fills in a gap in the
.NET framework by propagating thread-local variables from parent
to child threads, and by providing a ThreadStarting event.</summary>
<remarks>
This class is a decorator for the Thread class and thus a
drop-in replacement, except that only the most common methods and
properties (both static and non-static) are provided.
<para/>
A child thread inherits a thread-local value from a parent thread
only if ForkThread.AllocateDataSlot, ForkThread.AllocateNamedDataSlot
or ForkThread.GetNamedDataSlot was called to create the variable.
Sadly, there is no way to provide inheritance for variables marked by
[ThreadStatic].
<para/>
TODO: rewrite ThreadState property for .NET compact framework.
</remarks>
</member>
<member name="M:Loyc.Threading.ThreadEx.Start">
<summary>
Causes the operating system to change the state of the current instance to
System.Threading.ThreadState.Running.
</summary>
</member>
<member name="M:Loyc.Threading.ThreadEx.Start(System.Object)">
<summary>
Causes the operating system to change the state of the current instance to
System.Threading.ThreadState.Running. Start() does not return until the
ThreadStarted event is handled.
</summary><remarks>
Once the thread terminates, it CANNOT be restarted with another call to Start.
</remarks>
</member>
<member name="M:Loyc.Threading.ThreadEx.Abort(System.Object)">
<summary>
Raises a System.Threading.ThreadAbortException in the thread on which it
is invoked, to begin the process of terminating the thread while also providing
exception information about the thread termination. Calling this method usually
terminates the thread.
</summary>
</member>
<member name="M:Loyc.Threading.ThreadEx.Abort">
<inheritdoc cref="M:Loyc.Threading.ThreadEx.Abort(System.Object)"/>
</member>
<member name="M:Loyc.Threading.ThreadEx.GetDomain">
<summary>
Returns the current domain in which the current thread is running.
</summary>
</member>
<member name="M:Loyc.Threading.ThreadEx.GetHashCode">
<summary>
Returns a hash code for the current thread.
</summary>
</member>
<member name="M:Loyc.Threading.ThreadEx.Join">
<summary>
Blocks the calling thread until a thread terminates, while continuing to
perform standard COM and SendMessage pumping.
</summary>
</member>
<member name="M:Loyc.Threading.ThreadEx.Join(System.Int32)">
<summary>
Blocks the calling thread until a thread terminates or the specified time
elapses, while continuing to perform standard COM and SendMessage pumping.
</summary>
</member>
<member name="M:Loyc.Threading.ThreadEx.Sleep(System.Int32)">
<summary>
Suspends the current thread for a specified time.
</summary>
</member>
<member name="E:Loyc.Threading.ThreadEx.ThreadStarting">
<summary>
This event is called in the context of a newly-started thread, provided
that the thread is started by the Start() method of this class (rather
than Thread.Start()).
</summary>
<remarks>The Start() method blocks until this event completes.</remarks>
</member>
<member name="E:Loyc.Threading.ThreadEx.ThreadStopping">
<summary>
This event is called when a thread is stopping, if the thread is stopping
gracefully and provided that it was started by the Start() method of this
class (rather than Thread.Start()).
</summary>
</member>
<member name="P:Loyc.Threading.ThreadEx.CurrentThread">
<summary>
Gets the currently running thread.
</summary>
</member>
<member name="P:Loyc.Threading.ThreadEx.IsBackground">
<summary>
Gets or sets a value indicating whether or not a thread is a background thread.
</summary>
</member>
<member name="P:Loyc.Threading.ThreadEx.ManagedThreadId">
<summary>
Gets a unique identifier for the current managed thread.
</summary>
</member>
<member name="P:Loyc.Threading.ThreadEx.Name">
<summary>
Gets or sets the name of the thread.
</summary>
</member>
<member name="P:Loyc.Threading.ThreadEx.Priority">
<summary>
Gets or sets a value indicating the scheduling priority of a thread.
</summary>
</member>
<member name="P:Loyc.Threading.ThreadEx.ThreadState">
<summary>
Gets a value containing the states of the current thread.
</summary>
</member>
<member name="T:Loyc.Threading.TinyReaderWriterLock">
<summary>
A fast, tiny 4-byte lock to support multiple readers or a single writer.
Designed for low-contention, high-performance scenarios where reading is
common and writing is rare.
</summary>
<remarks>
Do not use the default constructor! Use TinyReaderWriterLock.New as the
initial value of the lock.
<para/>
Recursive locking is not supported: the same lock cannot be acquired twice
for writing on the same thread, nor can a reader lock be acquired after
the writer lock was acquired on the same thread. If you make either of
these mistakes, the lock will throw an NotSupportedException.
<para/>
You also cannot acquire a read lock followed recursively by a write lock,
either. Attempting to do so will self-deadlock the thread, bacause
TinyReaderWriterLock does not track the identity of each reader and is not
aware that it is waiting for the current thread to finish reading.
<para/>
However, multiple reader locks can be acquired on the same thread, just as
multiple reader locks can be acquired by different threads.
<para/>
Make sure you call ExitRead() or ExitWrite() in a finally block! When
compiled in debug mode, TinyReaderWriterLock will make sure you don't mix
up ExitRead() and ExitWrite().
<para/>
The range of Thread.CurrentThread.ManagedThreadId is undocumented. I have
assumed they don't use IDs close to int.MinValue, so I use values near
int.MinValue to indicate the number of readers holding the lock.
</remarks>
</member>
<member name="M:Loyc.Threading.TinyReaderWriterLock.EnterReadLock">
<summary>Acquires the lock to protect read access to a shared resource.</summary>
</member>
<member name="M:Loyc.Threading.TinyReaderWriterLock.ExitReadLock">
<summary>Releases a read lock that was acquired with EnterRead().</summary>
</member>
<member name="M:Loyc.Threading.TinyReaderWriterLock.EnterWriteLock">
<summary>Acquires the lock to protect write access to a shared resource.</summary>
</member>
<member name="M:Loyc.Threading.TinyReaderWriterLock.EnterWriteLock(System.Int32)">
<summary>Acquires the lock to protect write access to a shared resource.</summary>
<param name="threadID">Reports the value of Thread.CurrentThread.ManagedThreadId</param>
</member>
<member name="M:Loyc.Threading.TinyReaderWriterLock.ExitWriteLock">
<summary>Releases a write lock that was acquired with EnterWrite().</summary>
</member>
<member name="T:Loyc.Threading.ThreadLocalVariable`1">
<summary>Provides access to a thread-local variable through a dictionary
that maps thread IDs to values.</summary>
<typeparam name="T">Type of variable to wrap</typeparam>
<remarks>
This class exists to solve two problems. First, the [ThreadStatic]
attribute is not supported in the .NET Compact Framework. Second, and
more importantly, .NET does not propagate thread-local variables when
creating new threads, which is a huge problem if you want to implement
the <a href="http://loyc-etc.blogspot.com/2010/08/pervasive-services-and-di.html">
Ambient Service Pattern</a>. This class copies the T value from a parent
thread to a child thread, but because .NET provides no way to hook into
thread creation, it only works if you use <see cref="T:Loyc.Threading.ThreadEx"/> instead
of standard threads.
<para/>
ThreadLocalVariable implements thread-local variables using a dictionary
that maps thread IDs to values.
<para/>
Variables of this type are typically static and they must NOT be marked
with the [ThreadStatic] attribute.
<para/>
ThreadLocalVariable(of T) is less convenient than the [ThreadStatic]
attribute, but ThreadLocalVariable works with ThreadEx to propagate the
value of the variable from parent threads to child threads, and you can
install a propagator function to customize the way the variable is
copied (e.g. in case you need a deep copy).
<para/>
Despite my optimizations, ThreadLocalVariable is just over half as fast
as a ThreadStatic variable in CLR 2.0, in a test with no thread
contention. Access to the dictionary accounts for almost half of the
execution time; try-finally (needed in case of asyncronous exceptions)
blocks use up 11%; calling Thread.CurrentThread.ManagedThreadId takes
about 9%; and the rest, I presume, is used up by the TinyReaderWriterLock.
<para/>
TODO: consider switching from TinyReaderWriterLock+Dictionary to
ConcurrentDictionary which has fine-grained locking (.NET 4 only).
</remarks>
</member>
<member name="M:Loyc.Threading.ThreadLocalVariable`1.#ctor(`0)">
<summary>Constructs a ThreadLocalVariable.</summary>
<param name="initialValue">Initial value on the current thread;
also used as the FallbackValue in threads that are not created
via ThreadEx and in other threads that are already running.</param>
</member>
<member name="M:Loyc.Threading.ThreadLocalVariable`1.#ctor(`0,`0,Loyc.Threading.ThreadLocalVariable{`0}.Func{`0,`0})">
<summary>Constructs a ThreadLocalVariable.</summary>
<param name="initialValue">Initial value on the current thread.
Does not affect other threads that are already running.</param>
<param name="fallbackValue">Value to use when a given thread
doesn't have an associated value.</param>
<param name="propagator">A function that copies (and possibly
modifies) the Value from a parent thread when starting a new
thread.</param>
</member>
<member name="P:Loyc.Threading.ThreadLocalVariable`1.Value">
<summary>Value of the thread-local variable.</summary>
<remarks>
This property returns FallbackValue if no value exists for this thread.
</remarks>
</member>
<member name="P:Loyc.Threading.ThreadLocalVariable`1.FallbackValue">
<summary>
When a thread is not created using ThreadEx, the value of your
ThreadLocalVariable fails to propagate from the parent thread to the
child thread. In that case, Value takes on the value of FallbackValue
the first time it is called.
</summary>
<remarks>
By default, the FallbackValue is the initialValue passed to the
constructor.
</remarks>
</member>
<member name="T:Loyc.Threading.ScratchBuffer`1">
<summary>Holds a single Value that is associated with the thread that
assigned it.</summary>
<remarks>
ScratchBuffer is typically used as a static variable to hold a temporary
object used for operations that are done frequently and require a
temporary memory space--but only during the operation, not afterward.
<para/>
For example, CPTrie may require a temporary byte array during searches.
Re-creating the byte array for every search might cause a too much time
to be spent garbage-collecting. On the other hand, if CPTrie keeps a
reference to the temporary buffer in itself, what if a program contains
many instances of CPTrie? Each one would have its own separate temporary
buffer, wasting memory. The buffer can't be a straightforward global
variable, either, in case two threads need a scratch buffer at once.
ScratchBuffer, then, exists to prevent two threads from using the same
buffer.
<para/>
ScratchBuffer is designed with the assumption that creating a scratch
buffer is fast, but re-using an existing buffer is faster. Since
creating a scratch buffer is cheap already, this class is worthless
unless it is even cheaper. Therefore, it does not hold a buffer for
each thread, since managing multiple buffers would be too expensive;
and volatile variable access is used instead of locking.
<para/>
ScratchBuffer originally returned null if the scratch buffer had not
been initialized or was associated with a different thread, requiring
the caller to create a new buffer manually. Now there is a new constructor
that takes a factory function, which is called automatically by the Value
property if the scratch buffer is null or belongs to another thread. If
you use this constructor, then you do longer have to worry about Value
returning null.
<example>
static ScratchBuffer<byte[]> _buf =
new ScratchBuffer<byte[]>(() => new byte[40]);
// A method called a million times that needs a scratch buffer each time
void FrequentOperation()
{
byte[] buf = _buf.Value;
// do something here involving the buffer ...
}
</example>
Arguably it is better to use a [ThreadStatic] variable is instead of
ScratchBuffer, but FWIW [ThreadStatic] is not available on the .NET
Compact Framework.
</remarks>
</member>
<!-- Badly formed XML comment ignored for member "P:Loyc.Threading.ScratchBuffer`1.Value" -->
<member name="T:Loyc.Pair`2">
<summary>A tuple of two values, in a struct.</summary>
</member>
<member name="T:Loyc.Triplet`3">
<summary>A tuple of three values, in a struct.</summary>
</member>
<member name="T:Loyc.Holder`1">
<summary>A trivial class that holds a single value of type T in the
<see cref="P:Loyc.Holder`1.Value"/> property.
</summary><remarks>
This class is useful mainly as an alternative to standard boxing. When you
box a structure in C#, you lose access to the members of that structure.
This class, in contrast, provides access to the "boxed" value.
</remarks>
</member>
<member name="P:Loyc.Holder`1.Value">
<summary>Any value of type T.</summary>
</member>
<member name="T:Loyc.G">
<summary>Contains global functions that don't really belong in any class.</summary>
</member>
<member name="M:Loyc.G.Verify(System.Boolean)">
<summary>Same as Debug.Assert except that the argument is evaluated
even in a Release build.</summary>
</member>
<member name="M:Loyc.G.UnescapeCStyle(System.String)">
<summary>Unescapes a string that uses C-style escape sequences, e.g. "\n\r" becomes @"\n\r".</summary>
</member>
<member name="M:Loyc.G.UnescapeCStyle(System.String,System.Int32,System.Int32,System.Boolean)">
<summary>Unescapes a string that uses C-style escape sequences, e.g. "\n\r" becomes @"\n\r".</summary>
<param name="removeUnnecessaryBackslashes">Causes the backslash before
an unrecognized escape sequence to be removed, e.g. "\z" => "z".</param>
</member>
<member name="M:Loyc.G.UnescapeChar(System.String,System.Int32@)">
<summary>Unescapes a single character of a string, e.g.
<c>int = 3; UnescapeChar("foo\\n", ref i) == '\n'</c>. Returns the
character at 'index' if it is not a backslash, or if it is a
backslash but no escape sequence could be discerned.</summary>
<exception cref="T:System.IndexOutOfRangeException">The index was invalid.</exception>
</member>
<member name="M:Loyc.G.PushTLV``1(Loyc.Threading.ThreadLocalVariable{``0},``0)">
<summary>Helper function for a using statement that temporarily
modifies a thread-local variable.</summary>
<param name="variable">Variable to change</param>
<param name="newValue">New value</param>
<example>
// Temporarily change the target of compiler error messages
using (var _ = G.PushTLV(CompilerOutput.Writer, CustomWriter))
{
Warning.Write(SourcePos.Nowhere, "This message will go to a custom writer");
}
Warning.Write(SourcePos.Nowhere, "But this message will go to the original one");
</example>
</member>
<member name="M:Loyc.G.TryParseAt(System.String,System.Int32@,System.Int32@,System.Int32,System.Boolean)">
<summary>Tries to parse a string to an integer. Unlike <see cref="M:System.Int32.TryParse(System.String,System.Int32@)"/>,
this method allows parsing to start at any point in the string, it
allows non-numeric data after the number, and it can parse numbers that
are not in base 10.</summary>
<param name="base">Number base, e.g. 10 for decimal and 2 for binary.</param>
<param name="index">Location at which to start parsing</param>
<param name="skipSpaces">Whether to skip spaces before parsing. Only
the ' ' and '\t' characters are treated as spaces. No space is allowed
between '-' and the digits of a negative number, even with this flag.</param>
<param name="stopBeforeOverflow">Changes overflow handling behavior
so that the result does not overflow, and the digit(s) at the end of
the string, that would have caused overflow, are ignored. In this case,
the return value is still false.</param>
<returns>True if a number was found starting at the specified index
and it was successfully converted to a number, or false if not.</returns>
<remarks>
This method never throws. If parsing fails, index is left unchanged,
except that spaces are still skipped if you set the skipSpaces flag.
If base>36, parsing can succeed but digits above 35 (Z) cannot occur
in the output number. If the input number cannot fit in 'result', the
return value is false but index increases anyway, and 'result' is a
bitwise truncated version of the number.
<para/>
When parsing input such as "12.34", the parser stops and returns true
at the dot (with a result of 12 in this case).
</remarks>
</member>
<member name="M:Loyc.G.TryParseAt(System.String,System.Int32@,System.Int64@,System.Int32,System.Boolean)">
<inheritdoc cref="!:TryParseAt(this string, ref int, out int, int, bool)"/>
</member>
<member name="M:Loyc.G.TryParseAt(System.String,System.Int32@,System.UInt64@,System.Int32,Loyc.G.ParseFlag)">
<inheritdoc cref="!:TryParseAt(this string, ref int, out int, int, bool)"/>
</member>
<member name="M:Loyc.G.SkipSpaces(System.String,System.Int32)">
<summary>Gets the index of the first non-space character after the specified index.</summary>
<remarks>Only ' ' and '\t' are treated as spaces. If the index is invalid, it is returned unchanged.</remarks>
</member>
<member name="T:Loyc.G.ParseFlag">
<summary>Flags that can be used with the overload of TryParseAt()
that parses unsigned integers.</summary>
</member>
<member name="F:Loyc.G.ParseFlag.SkipSpacesInFront">
<summary>Skip spaces before the number. Without this flag, spaces make parsing fail.</summary>
</member>
<member name="F:Loyc.G.ParseFlag.SkipSpacesInsideNumber">
<summary>Skip spaces inside the number. Without this flag, spaces make parsing stop.</summary>
</member>
<member name="F:Loyc.G.ParseFlag.StopBeforeOverflow">
<summary>Changes overflow handling behavior so that the result does
not overflow, and the digit(s) at the end of the string, that would
have caused overflow, are ignored. In this case, the return value is
still false.</summary>
</member>
<member name="F:Loyc.G.ParseFlag.SkipUnderscores">
<summary>Skip underscores inside number. Without this flag, underscores make parsing stop.</summary>
</member>
<!-- Badly formed XML comment ignored for member "T:Loyc.Collections.KeyCollection`2" -->
<member name="T:Loyc.HashTags`1">
<summary>
An implementation of IAttributes that can hold one attribute before
allocating any memory for a hashtable. It is intended to be used as
a base class but can be used on its own.
</summary>
</member>
<member name="P:Loyc.ITags`1.Tags">
<summary>Returns a dictionary that can be used to store additional state
beyond the standard content of the object.
</summary><remarks>
Tags is never null or read-only.
<para/>
Tags of AstNodes should normally hold transient or derived information,
not information that is part of the node's syntax.
<para/>
Is is possible that Tags==this to reduce overhead.
</remarks>
</member>
<member name="T:Loyc.Math.RectangleExt">
<summary>Contains methods to manipulate rectangles.</summary>
<remarks>Unfortunately, C# often can't infer the type parameters. Many of
these methods must be called with explicit type parameters.</remarks>
</member>
<member name="M:Loyc.Math.RectangleExt.Union``2(``0,``0)">
<summary>Computes the union of two <i>normalized</i> rectangles,
i.e. a rectangle large enough to cover both original rectangles.</summary>
<remarks>The results may be incorrect if one or both rectangles
are not normalized.</remarks>
</member>
<member name="M:Loyc.Math.RectangleExt.Intersect``2(``0,``0)">
<summary>Computes the intersection of two <i>normalized</i> rectangles,
i.e. the region covered by both original rectangles.</summary>
<remarks>The results may be incorrect if one or both rectangles are
not normalized. If the rectangles do not overlap, a non-normalized
rectangle is returned.</remarks>
</member>
<member name="M:Loyc.Math.RectangleExt.ExpandToInclude``3(``0,``1)">
<summary>Expands a rectangle's boundaries to include a given point.</summary>
<returns>Returns true if the rectangle changed.</returns>
</member>
<member name="M:Loyc.Math.RectangleExt.ExpandToInclude``3(``0,System.Collections.Generic.IEnumerable{``1})">
<summary>Expands a rectangle's boundaries to include a series of points.</summary>
<returns>Returns true if the rectangle changed.</returns>
</member>
<member name="M:Loyc.Math.RectangleExt.Contains``3(``0,``1)">
<summary>Determines whether a rectangle contains a given point.</summary>
<remarks>Returns false if the rectangle is not normalized.</remarks>
</member>
<member name="M:Loyc.Math.RectangleExt.Contains``2(``0,``0)">
<summary>Determines whether a rectangle fully contains another rectangle.</summary>
<remarks>May not work correctly if either of the rectangles is not normalized.</remarks>
</member>
<member name="M:Loyc.Math.RectangleExt.Overlaps``2(``0,``0)">
<summary>Determines whether a rectangle overlaps another rectangle.</summary>
<remarks>May not work correctly if either of the rectangles is not normalized.</remarks>
</member>
<member name="T:Loyc.Collections.NegListSource`1">
<summary>
Provides a view of an <see cref="T:Loyc.Collections.IListSource`1"/> in which the Count is the same, but the
minimum index is not necessarily zero. Returned from <see cref="M:Loyc.Collections.LCExt.NegView``1(Loyc.Collections.IListSource{``0},System.Int32)"/>.
</summary>
<remarks>
This wrapper is a structure in order to offer high performance in certain
scenarios.
<para/>
Like ListSourceSlice, this structure provides a view of another list
starting at a certain offset. Unlike ListSourceSlice, however, this
structure allows the caller to access the entire original list, not just a
slice.
</remarks>
</member>
<member name="M:Loyc.Collections.NegListSource`1.#ctor(Loyc.Collections.IListSource{`0},System.Int32)">
<summary>Initializes a NegListSource wrapper.</summary>
<param name="list">A list to wrap (must not be null).</param>
<param name="zeroOffset">An index into the original list. this[0] will refer to that index.</param>
<remarks>The zeroOffset can be any integer, but if it is not in the range 0 to list.Count-1, this[0] will not be valid.</remarks>
</member>
<member name="M:Loyc.Collections.NegListSource`1.TryGet(System.Int32,System.Boolean@)">
<inheritdoc/>
</member>
<member name="M:Loyc.Collections.NegListSource`1.Equals(System.Object)">
<inheritdoc cref="!:Loyc.Essentials.WrapperBase<T>.Equals"/>
</member>
<member name="M:Loyc.Collections.NegListSource`1.ToString">
<summary>Returns ToString() of the wrapped list.</summary>
</member>
<member name="P:Loyc.Collections.NegListSource`1.OriginalList">
<summary>Gets the list that was passed to the constructor of this instance.</summary>
</member>
<member name="P:Loyc.Collections.NegListSource`1.Offset">
<summary>Returns the offset added to indexes in the original list, which equals -Min.</summary>
<remarks>The 0th item in this list the same as OriginalList[Offset].</remarks>
<remarks>
WARNING: this is a value type. Calling the setter may have unexpected
consequences for people unfamiliar with the .NET type system, because
it is easy to make copies accidentally, and changing the Offset in a copy
does not change the Offset in the original.
</remarks>
</member>
<member name="P:Loyc.Collections.NegListSource`1.Count">
<summary>Returns the total number of items in the list (same as OriginalList.Count).</summary>
</member>
<member name="P:Loyc.Collections.NegListSource`1.Min">
<summary>Returns the minimum valid index.</summary>
</member>
<member name="P:Loyc.Collections.NegListSource`1.Max">
<summary>Returns the maximum valid index, which is Min + OriginalList.Count - 1.</summary>
</member>
<member name="P:Loyc.Collections.NegListSource`1.Item(System.Int32)">
<summary>Gets the value of the list at the specified index. In terms
of the original list, this is OriginalList[index + Offset]</summary>
<param name="index">An index in the range Min to Max.</param>
<exception cref="T:System.ArgumentOutOfRangeException">The index provided is not
valid in this list.</exception>
</member>
<member name="T:Loyc.Symbol">
<summary>Represents a symbol, like the feature offered in Ruby.</summary>
<remarks>
Call GSymbol.Get() to create a Symbol from a string, or GSymbol.GetIfExists()
to find a Symbol that has already been created.
<para/>
Symbols can be used like a global, extensible enumeration. Comparing symbols
is as fast as comparing two integers; this is because '==' is not
overloaded--equality is defined as reference equality, as there is only one
instance of a given Symbol.
<para/>
Symbols can also be produced in namespaces called "pools". Two Symbols with
the same name, but in different pools, are considered to be different
symbols. Using a derived class D of Symbol and a SymbolPool<D>,
you can make Symbols that are as type-safe as enums.
<para/>
A Symbol's ToString() function formerly returned the symbol name prefixed
with a colon (:), following the convention of the Ruby language, from which
I got the idea of Symbols in the first place. However, since Symbols are
commonly used for extensible enums, I decided it was better that ToString()
return just the Name alone, which makes Symbol more suitable as a drop-in
replacement for enums.
</remarks>
</member>
<member name="T:Loyc.IReferenceComparable">
<summary>This is a tag which indicates that objects of this type are
unique; specifically, any two different objects that implement this
interface are always unequal (while one object is equal only to itself).</summary>
<remarks>
This interface is recognized by <see cref="!:Set<T>"/>, <see cref="!:SetI"/>
and <see cref="!:InternalSet<T>"/>. It causes normal comparison (via
<see cref="T:System.Collections.Generic.IEqualityComparer`1"/> to be skipped in favor of reference
comparison.
</remarks>
</member>
<member name="M:Loyc.Symbol.#ctor(System.Int32,System.String,Loyc.SymbolPool)">
<summary>For internal use only. Call GSymbol.Get() instead!</summary>
</member>
<member name="M:Loyc.Symbol.#ctor(Loyc.Symbol)">
<summary>For use by a derived class to produce a statically-typed
enumeration in a private pool. See the example under SymbolPool
(of SymbolEnum)</summary>
<param name="prototype">A strictly temporary Symbol that is used
to initialize this object. The derived class should discard the
prototype after calling this constructor.</param>
</member>
<member name="P:Loyc.Symbol.Name">
<summary>Gets the name of the Symbol.</summary>
</member>
<member name="P:Loyc.Symbol.Pool">
<summary>Gets the <see cref="T:Loyc.SymbolPool"/> in which this Symbol was created.</summary>
</member>
<member name="P:Loyc.Symbol.IsGlobal">
<summary>Returns true if this symbol is in the global pool (<see cref="F:Loyc.GSymbol.Pool"/>).</summary>
</member>
<member name="P:Loyc.Symbol.Id">
<summary>Returns a numeric ID for the Symbol.</summary>
<remarks>Normally the Id is auto-assigned and the Id corresponding to
a particular Name may vary between different runs of the same program.
However, <see cref="M:Loyc.SymbolPool.Get(System.String,System.Int32)"/> can be used to
assign a specific Id to a Name when setting up a new pool.</remarks>
</member>
<member name="T:Loyc.GSymbol">
<summary>This class produces global symbols.</summary>
<remarks>
Call GSymbol.Get() to create a Symbol from a string, or GSymbol.GetIfExists()
to find a Symbol that has already been created.
<para/>
Symbols in the global pool are weak-referenced to allow garbage collection.
</remarks>
</member>
<member name="T:Loyc.SymbolPool">
<summary>Tracks a set of symbols.</summary>
<remarks>
There is one global symbol pool (GSymbol.Pool) and you can create an
unlimited number of private pools, each with an independent namespace.
<para/>
Methods of this class are synchronized, so a SymbolPool can be used from
multiple threads.
<para/>
By default, SymbolPool uses weak references to refer to Symbols, so they
can be garbage-collected when no longer in use. When creating a private
pool you can tell the SymbolPool constructor to use strong references
instead, which ensures that none of the symbols disappear, but risks a
memory leak if the pool itself is never garbage-collected. Strong
references also require less memory and may be slightly faster.
<para/>
By default, all Symbol are given non-negative IDs. GSymbol.Empty (whose
Name is "") has an Id of 0, but in a private pool, "" is not treated
differently than any other symbol so a new ID will be allocated for it.
</remarks>
</member>
<member name="T:Loyc.Collections.IAutoCreatePool`2">
<summary>Represents a pool of objects in which an object is
automatically created when requested by its key.</summary>
<typeparam name="TKey">Key type.</typeparam>
<typeparam name="TValue">Value type.</typeparam>
<remarks>This design assumes that the values in the pool know their own
key, so it implements IEnumerable{TValue} rather than
IEnumerable{KeyValuePair{TKey,TValue}}.</remarks>
</member>
<member name="M:Loyc.Collections.IAutoCreatePool`2.GetIfExists(`0)">
<summary>Gets the item with the specified key, if it was created earlier.</summary>
<returns>The value corresponding to the specified key, or default(T) if
the value has not been created.</returns>
</member>
<member name="P:Loyc.Collections.IAutoCreatePool`2.Item(`0)">
<summary>Gets the item at the specified index.</summary>
<exception cref="T:System.ArgumentOutOfRangeException">The index was not valid
in this list.</exception>
<param name="index">An index in the range 0 to Count-1.</param>
<returns>The element at the specified index.</returns>
</member>
<member name="M:Loyc.SymbolPool.new(System.Int32,System.Boolean,System.Int32)">
<summary>Initializes a new Symbol pool.</summary>
<param name="firstID">The first Symbol created in the pool will have
the specified ID number, and IDs will proceed downward from there.</param>
<param name="useStrongRefs">True to use strong references to the
Symbols in the pool, false to use WeakReferences that allow garbage-
collection of individual Symbols.</param>
<param name="poolId">Numeric ID of the pool (affects the HashCode of
Symbols from the pool)</param>
</member>
<member name="M:Loyc.SymbolPool.Get(System.String)">
<summary>Gets a symbol from this pool, or creates it if it does not
exist in this pool already.</summary>
<param name="name">Name to find or create.</param>
<returns>A symbol with the requested name, or null if the name was null.</returns>
<remarks>
If Get("foo") is called in two different pools, two Symbols will be
created, each with the Name "foo" but not necessarily with the same
IDs. Note that two private pools re-use the same IDs, but this
generally doesn't matter, as Symbols are compared by reference, not by
ID.
</remarks>
</member>
<member name="M:Loyc.SymbolPool.Get(System.String,System.Int32)">
<summary>Creates a Symbol in this pool with a specific ID, or verifies
that the requested Name-Id pair is present in the pool.</summary>
<param name="name">Name to find or create.</param>
<param name="id">Id that must be associated with that name.</param>
<exception cref="T:System.ArgumentNullException">name was null.</exception>
<exception cref="T:System.ArgumentException">The specified Name or Id is already
in use, but the Name and Id do not match. For example, Get("a", 1) throws
this exception if a Symbol with Id==1 is not named "a", or a Symbol with
Name=="a" does not have Id==1.</exception>
<returns>A symbol with the requested Name and Id.</returns>
</member>
<member name="M:Loyc.SymbolPool.Get(System.String,Loyc.Symbol@)">
<summary>Workaround for lack of covariant return types in C#</summary>
</member>
<member name="M:Loyc.SymbolPool.Get(System.String,System.Int32,Loyc.Symbol@)">
<summary>Workaround for lack of covariant return types in C#</summary>
</member>
<member name="M:Loyc.SymbolPool.NewSymbol(System.Int32,System.String)">
<summary>Factory method to create a new Symbol.</summary>
</member>
<member name="M:Loyc.SymbolPool.GetIfExists(System.String)">
<summary>Gets a symbol from this pool, if the name exists already.</summary>
<param name="name">Symbol Name to find</param>
<returns>Returns the existing Symbol if found; returns null if the name
was not found, or if the name itself was null.</returns>
</member>
<member name="M:Loyc.SymbolPool.GetGlobalOrCreateHere(System.String)">
<summary>Gets a symbol from the global pool, if it exists there already;
otherwise, creates a Symbol in this pool.</summary>
<param name="name">Name of a symbol to get or create</param>
<returns>A symbol with the requested name</returns>
</member>
<member name="M:Loyc.SymbolPool.GetById(System.Int32)">
<summary>Gets a symbol by its ID, or null if there is no such symbol.</summary>
<param name="id">ID of a symbol. If this is a private pool and the
ID does not exist in the pool, the global pool is searched instead.
</param>
<remarks>
GetById() uses a dictionary of ID numbers to Symbols for fast lookup.
To save time and memory, this dictionary is not created until either
GetById() or Get(string name, int id) is called.
</remarks>
<returns>The requested Symbol, or null if not found.</returns>
</member>
<member name="P:Loyc.SymbolPool.Item(System.String)">
<inheritdoc cref="M:Loyc.SymbolPool.Get(System.String)"/>
</member>
<member name="P:Loyc.SymbolPool.TotalCount">
<summary>Returns the number of Symbols created in this pool.</summary>
</member>
<member name="T:Loyc.SymbolPool`1">
<summary>This type of SymbolPool helps create more strongly typed Symbols
that simulate enums, but provide extensibility. Specifically, it
creates SymbolE objects, where SymbolE is some derived class of Symbol.
</summary>
<typeparam name="SymbolE">
A derived class of Symbol that owns the pool. See the example below.
</typeparam>
<example>
public class ShapeType : Symbol
{
private ShapeType(Symbol prototype) : base(prototype) { }
public static new readonly SymbolPool<ShapeType> Pool
= new SymbolPool<ShapeType>(p => new ShapeType(p));
public static readonly ShapeType Circle = Pool.Get("Circle");
public static readonly ShapeType Rect = Pool.Get("Rect");
public static readonly ShapeType Line = Pool.Get("Line");
public static readonly ShapeType Polygon = Pool.Get("Polygon");
}
</example>
</member>
<member name="T:Loyc.Collections.ISetTests`1">
<summary>Set testing operations.</summary>
<typeparam name="SetT">Type of set that this set can be tested against.</typeparam>
</member>
<member name="T:Loyc.Collections.ISetOperations`2">
<summary>Set-combining operations: With, Without, Union, Intersect, Except, Xor.</summary>
<typeparam name="T">Type of items in the set.</typeparam>
<typeparam name="SetT">Type of the set itself.</typeparam>
</member>
<member name="T:Loyc.Collections.ISetImm`2">
<summary>Immutable set operations.</summary>
<typeparam name="SetT">Type of this set.</typeparam>
<typeparam name="T">Type of items in the set</typeparam>
</member>
<member name="P:Loyc.Collections.ISetImm`2.IsInverted">
<summary>Returns true if the set is inverted, which means that the
enumerator returns all the items that are <i>not</i> in the set,
and the <see cref="!:Count"/> returns the number of items that are
not in the set.</summary>
<remarks><see cref="!:InvertibleSet<T>"/> is an example of a set that
can be inverted. In most set implementations, this property always
returns false.</remarks>
</member>
<member name="T:Loyc.Threading.PushedTLV`1">
<summary>
Designed to be used in a "using" statement to alter a thread-local variable
temporarily.
</summary>
</member>
<member name="T:Loyc.Collections.IAutoSizeArray`1">
<summary>An auto-sizing array is a list structure that allows you to modify
the element at any index, including indices that don't yet exist; the
collection automatically adds missing indices.</summary>
<typeparam name="T">Data type of each element.</typeparam>
<remarks>
This interface begins counting elements at index zero. The <see cref="T:Loyc.Collections.INegAutoSizeArray`1"/> interface supports negative indexes.
</remarks>
</member>
<member name="M:Loyc.Collections.IAutoSizeArray`1.Optimize">
<summary>Optimizes the data structure to consume less memory or storage space.</summary>
<remarks>
A simple auto-sizing array can implement this method by examining the
final elements and removing any that are equal to default(T).
</remarks>
</member>
<member name="T:Loyc.Collections.ListSourceAsList`1">
<summary>A read-only wrapper that implements IList(T) and IListSource(T),
returned from <see cref="M:Loyc.Collections.LCExt.AsList``1(Loyc.Collections.IListSource{``0})"/>.</summary>
</member>
<member name="T:Loyc.Math.IComplexMath`1">
<summary>
Use this interface for types such as complex numbers that satisfy
the field axioms but do not have a natural order.
complex numbers of course do support IHasRoot.
</summary>
</member>
<member name="T:Loyc.Collections.SelectNegLists`1">
<summary>
Provides view of an <see cref="T:System.Collections.Generic.IList`1"/> in which element [i] is a
<see cref="T:Loyc.Collections.NegList`1"/> N such that N[0] refers to element [i] in the
original list. See <see cref="M:Loyc.Collections.LCExt.NegLists``1(System.Collections.Generic.IList{``0})"/> for more
information.
</summary>
<seealso cref="T:Loyc.Collections.SelectNegListSources`1"/>
</member>
<member name="T:Loyc.Collections.ReverseBinumerator`1">
<summary>A <see cref="T:Loyc.Collections.IBinumerator`1"/> that swaps the MoveNext() and MovePrev() methods.</summary>
</member>
<member name="T:Loyc.Collections.Repeated`1">
<summary>A sequence that simply repeats the same value a specified number
of times, returned from <see cref="!:LCExt.Repeat<T>"/>.</summary>
</member>
<member name="M:Loyc.Collections.ArraySlice`1.#ctor(`0[],System.Int32,System.Int32)">
<summary>Initializes an array slice.</summary>
<exception cref="T:System.ArgumentException">The start index was below zero.</exception>
<remarks>The (start, count) range is allowed to be invalid, as long
as 'start' is zero or above.
<ul>
<li>If 'count' is below zero, or if 'start' is above the original Length,
the Count of the new slice is set to zero.</li>
<li>if (start + count) is above the original Length, the Count of the new
slice is reduced to <c>list.Length - start</c>.</li>
</ul>
</remarks>
</member>
<member name="T:Loyc.Math.MathEx">
<summary>
Provides additional math functions that are not available in System.Math.
</summary>
</member>
<member name="M:Loyc.Math.MathEx.Sign(System.Int64)">
<summary>Returns the sign of a number (-1 for negative, 1 for positive, 0 for zero).</summary>
</member>
<member name="M:Loyc.Math.MathEx.Sign(System.Int32)">
<summary>Returns the sign of a number (-1 for negative, 1 for positive, 0 for zero).</summary>
</member>
<member name="M:Loyc.Math.MathEx.Sign(System.Double)">
<summary>Returns the sign of a number (-1 for negative, 1 for positive, 0 for zero).</summary>
</member>
<member name="M:Loyc.Math.MathEx.MulShift(System.Int32,System.Int32,System.Int32)">
<summary>Multiplies two integers, internally producing a double-size
result so that overflow is not possible, then divides the result by the
specified power of two using a right shift.</summary>
<returns>a * mulBy >> shiftBy, without overflow during multiplication.</returns>
<remarks>This method does not handle the case that the result is too
large to fit in the original data type.</remarks>
</member>
<member name="M:Loyc.Math.MathEx.MulShift(System.UInt32,System.UInt32,System.Int32)">
<inheritdoc cref="M:Loyc.Math.MathEx.MulShift(System.Int32,System.Int32,System.Int32)"/>
</member>
<member name="M:Loyc.Math.MathEx.MulShift(System.Int64,System.Int64,System.Int32)">
<inheritdoc cref="M:Loyc.Math.MathEx.MulShift(System.Int32,System.Int32,System.Int32)"/>
</member>
<member name="M:Loyc.Math.MathEx.MulShift(System.UInt64,System.UInt64,System.Int32)">
<inheritdoc cref="M:Loyc.Math.MathEx.MulShift(System.Int32,System.Int32,System.Int32)"/>
</member>
<member name="M:Loyc.Math.MathEx.MulDiv(System.Int32,System.Int32,System.Int32,System.Int32@)">
<summary>Multiplies two integers, internally producing a double-size
result so that overflow is not possible, then divides the result by the
specified number.</summary>
<param name="remainder">The remainder of the division is placed here.
The remainder is computed properly even if the main result overflows.</param>
<returns>a * mulBy / divBy, without overflow during multiplication.</returns>
<remarks>If the final result does not fit in the original data type,
this method returns largest possible value of the result type
(int.MaxValue, or int.MinValue if the overflowing result is negative).
</remarks>
</member>
<member name="M:Loyc.Math.MathEx.MulDiv(System.UInt32,System.UInt32,System.UInt32,System.UInt32@)">
<inheritdoc cref="M:Loyc.Math.MathEx.MulDiv(System.Int32,System.Int32,System.Int32,System.Int32@)"/>
<remarks>If the final result does not fit in the original data type,
this method returns largest possible value of the result type
(uint.MaxValue).</remarks>
</member>
<member name="M:Loyc.Math.MathEx.MulDiv(System.Int64,System.Int64,System.Int64,System.Int64@)">
<inheritdoc cref="M:Loyc.Math.MathEx.MulDiv(System.Int32,System.Int32,System.Int32,System.Int32@)"/>
<remarks>If the final result does not fit in the original data type,
this method returns largest possible value of the result type
(long.MaxValue, or long.MinValue if the overflowing result is negative).
</remarks>
</member>
<member name="M:Loyc.Math.MathEx.MulDiv(System.UInt64,System.UInt64,System.UInt64,System.UInt64@)">
<inheritdoc cref="M:Loyc.Math.MathEx.MulDiv(System.Int32,System.Int32,System.Int32,System.Int32@)"/>
<remarks>If the final result does not fit in the original data type,
this method returns largest possible value of the result type
(ulong.MaxValue).</remarks>
</member>
<member name="M:Loyc.Math.MathEx.MulDiv(System.Int32,System.Int32,System.Int32)">
<inheritdoc cref="!:MulDiv(int a, int mulBy, int divBy, out int remainder)"/>
</member>
<member name="M:Loyc.Math.MathEx.MulDiv(System.UInt32,System.UInt32,System.UInt32)">
<inheritdoc cref="!:MulDiv(uint a, uint mulBy, uint divBy, out uint remainder)"/>
</member>
<member name="M:Loyc.Math.MathEx.MulDiv(System.Int64,System.Int64,System.Int64)">
<inheritdoc cref="!:MulDiv(long a, long mulBy, long divBy, out long remainder)"/>
</member>
<member name="M:Loyc.Math.MathEx.MulDiv(System.UInt64,System.UInt64,System.UInt64)">
<inheritdoc cref="!:MulDiv(ulong a, ulong mulBy, ulong divBy, out ulong remainder)"/>
</member>
<member name="M:Loyc.Math.MathEx.RoL(System.UInt32,System.Int32)">
<summary>Rotates a bit pattern left by the specified number of bits.</summary>
</member>
<member name="M:Loyc.Math.MathEx.RoL(System.Int32,System.Int32)">
<summary>Rotates a bit pattern left by the specified number of bits.</summary>
</member>
<member name="M:Loyc.Math.MathEx.RoL(System.UInt64,System.Int32)">
<summary>Rotates a bit pattern left by the specified number of bits.</summary>
</member>
<member name="M:Loyc.Math.MathEx.RoL(System.Int64,System.Int32)">
<summary>Rotates a bit pattern left by the specified number of bits.</summary>
</member>
<member name="M:Loyc.Math.MathEx.RoL(System.UInt16,System.Int32)">
<summary>Rotates a bit pattern left by the specified number of bits.</summary>
</member>
<member name="M:Loyc.Math.MathEx.RoL(System.Byte,System.Int32)">
<summary>Rotates a bit pattern left by the specified number of bits.</summary>
</member>
<member name="M:Loyc.Math.MathEx.RoR(System.UInt32,System.Int32)">
<summary>Rotates a bit pattern right by the specified number of bits.</summary>
</member>
<member name="M:Loyc.Math.MathEx.RoR(System.Int32,System.Int32)">
<summary>Rotates a bit pattern right by the specified number of bits.</summary>
</member>
<member name="M:Loyc.Math.MathEx.RoR(System.UInt64,System.Int32)">
<summary>Rotates a bit pattern right by the specified number of bits.</summary>
</member>
<member name="M:Loyc.Math.MathEx.RoR(System.Int64,System.Int32)">
<summary>Rotates a bit pattern right by the specified number of bits.</summary>
</member>
<member name="M:Loyc.Math.MathEx.RoR(System.UInt16,System.Int32)">
<summary>Rotates a bit pattern right by the specified number of bits.</summary>
</member>
<member name="M:Loyc.Math.MathEx.RoR(System.Byte,System.Int32)">
<summary>Rotates a bit pattern right by the specified number of bits.</summary>
</member>
<member name="M:Loyc.Math.MathEx.Sqrt(System.Int64)">
Algorithms from http://aggregate.org/MAGIC and possibly
http://www.devmaster.net/articles/fixed-point-optimizations/ or
http://graphics.stanford.edu/~seander/bithacks.html
</member>
<member name="M:Loyc.Math.MathEx.CountOnes(System.UInt32)">
<summary>Returns the number of '1' bits in x</summary>
<remarks>
For example, CountOnes(0xF0) == 4.
<para/>
Some processors have a dedicated instruction for this operation, but
the .NET framework provides no access to it.
</remarks>
</member>
<member name="M:Loyc.Math.MathEx.CountOnes(System.Byte)">
<inheritdoc cref="M:Loyc.Math.MathEx.CountOnes(System.Int32)"/>
</member>
<member name="M:Loyc.Math.MathEx.CountOnes(System.UInt16)">
<inheritdoc cref="M:Loyc.Math.MathEx.CountOnes(System.Int32)"/>
</member>
<member name="M:Loyc.Math.MathEx.CountOnes(System.Int64)">
<inheritdoc cref="M:Loyc.Math.MathEx.CountOnes(System.Int32)"/>
</member>
<member name="M:Loyc.Math.MathEx.CountOnes(System.UInt64)">
<inheritdoc cref="M:Loyc.Math.MathEx.CountOnes(System.Int32)"/>
</member>
<member name="M:Loyc.Math.MathEx.Log2Floor(System.UInt32)">
<inheritdoc cref="M:Loyc.Math.MathEx.Log2Floor(System.Int32)"/>
</member>
<member name="M:Loyc.Math.MathEx.Log2Floor(System.Int32)">
<summary>
Returns the floor of the base-2 logarithm of x. e.g. 1024 -> 10, 1000 -> 9
</summary><remarks>
The return value is -1 for an input that is zero or negative.
<para/>
Some processors have a dedicated instruction for this operation, but
the .NET framework provides no access to it.
</remarks>
</member>
<member name="M:Loyc.Math.MathEx.Log2Floor(System.UInt64)">
<inheritdoc cref="M:Loyc.Math.MathEx.Log2Floor(System.Int32)"/>
</member>
<member name="M:Loyc.Math.MathEx.Log2Floor(System.Int64)">
<inheritdoc cref="M:Loyc.Math.MathEx.Log2Floor(System.Int32)"/>
</member>
<member name="M:Loyc.Math.MathEx.NextPowerOf2(System.UInt32)">
<summary>Gets the next higher power of 2, e.g. 4=>8, 13=>16.</summary>
<remarks>For negative values of x, NextPowerOf2((uint)x) is 0.</remarks>
</member>
<member name="M:Loyc.Math.MathEx.NextPowerOf2(System.UInt64)">
<summary>Gets the next higher power of 2, e.g. 4=>8, 13=>16.</summary>
<remarks>For negative values of (long)x, NextPowerOf2((ulong)x) is 0.</remarks>
</member>
<member name="M:Loyc.Math.MathEx.NextPowerOf2(System.Int32)">
<summary>Calls <see cref="M:Loyc.Math.MathEx.NextPowerOf2(System.UInt32)"/>.</summary>
</member>
<member name="M:Loyc.Math.MathEx.NextPowerOf2(System.Int64)">
<summary>Calls <see cref="M:Loyc.Math.MathEx.NextPowerOf2(System.UInt64)"/>.</summary>
</member>
<member name="M:Loyc.Math.MathEx.FindFirstOne(System.UInt32)">
<summary>Returns the bit position of the first '1' bit in a uint, or -1
the input is zero.</summary>
</member>
<member name="M:Loyc.Math.MathEx.FindFirstZero(System.UInt32)">
<summary>Returns the bit position of the first '0' bit in a uint, or -1
if there are no zeros.</summary>
</member>
<member name="M:Loyc.Math.MathEx.FindLastOne(System.UInt32)">
<summary>Returns the bit position of the first '1' bit in a uint, or -1
the input is zero.</summary>
</member>
<member name="T:Loyc.Math.IPoint3Base`1">
<summary>This interface exists to work around a limitation of C#; use
<see cref="T:Loyc.Math.IPoint`1"/> instead.</summary>
<remarks>
C# cannot combine a getter property and a setter property from two
interfaces, so this interface cannot inherit its getters from <see cref="T:Loyc.Math.IPoint3Reader`1"/>. The workaround is to define another getter in
the read-write interface for each getter in the read-only interface. As far
as the CLR is concerned, the two getters are unrelated, but you won't
notice that unless you need to explicitly implement this interface.
</remarks>
</member>
<member name="P:Loyc.Math.IPoint3Base`1.Z">
<summary>Z coordinate of a point or vector.</summary>
<remarks>
Z typically represents either the vertical or depth component of a
point or vector.
</remarks>
</member>
<member name="T:Loyc.Math.IPoint3`1">
<summary>A mutable 3D point with X, Y, and Z coordinates.</summary>
<remarks>
WARNING: When casting a point (or vector) structure to this interface,
it is boxed, making a copy. Changes made through a reference to IPoint3 do
not affect the original point!
<para/>
The coordinates of an IPoint3 are separated into a base interface,
<see cref="T:Loyc.Math.IPoint3Base`1"/>, for the same reason that <see cref="T:Loyc.Math.IPoint`1"/>'s
coordinates are separated into <see cref="T:Loyc.Math.IPointBase`1"/>, as explained in
the documentation of <see cref="T:Loyc.Math.IPoint`1"/>.
<para/>
For better or for worse, this interface design does not include the <see cref="!:IPoint<T>.New"/> method, so you cannot (via this interface alone)
convert a 3D point to a 2D point (although <see cref="T:Loyc.Math.IPointBase`1"/>
provides a 2D view.)
</remarks>
</member>
<member name="T:Loyc.Math.INewPoint3`2">
<summary>This interface exists to work around a limitation of C#; see
<see cref="T:Loyc.Math.IPoint`1"/> and <see cref="T:Loyc.Math.IPoint3`1"/>.</summary>
</member>
<member name="T:Loyc.Collections.INotifyListChanging`1">
<summary>
Encapsulates the <see cref="E:Loyc.Collections.INotifyListChanging`1.ListChanging"/> event that notifies listeners
of dynamic changes to an indexed list, such as when items get added and
removed or the whole list is refreshed.
</summary>
<typeparam name="T">Type of items in the list</typeparam>
<remarks>
This approach to change notification is more lightweight than the standard
<see cref="T:System.Collections.Specialized.INotifyCollectionChanged"/> interface because that interface
sends both a list of new items and a list of old items, so many changes
require a pair of temporary objects to be created that hold the two lists
of items.
<para/>
In contrast, the <see cref="E:Loyc.Collections.INotifyListChanging`1.ListChanging"/> event includes only one list
that specifies the set of new items. In the case of Remove events, no change
list is included. Since the collection has not been modified yet, the user
handling the event can examine the list to learn which item(s) are being
removed; if the list is being changed, it can similarly examine the list
to see the old set of items.
<para/>
An optimization is available when only a single item is being added or
changed. In that case, the collection class should create a lightweight
read-only single-item list by calling <see cref="!:Iterable.Single<T>(T)"/>.
Such a list has less overhead than <see cref="T:System.Collections.Generic.List`1"/> and the same
overhead as an array of one item.
</remarks>
</member>
<member name="E:Loyc.Collections.INotifyListChanging`1.ListChanging">
<summary>Occurs when the collection associated with this interface is
about to change.</summary>
<remarks>
The event handler receives a <see cref="T:Loyc.Collections.ListChangeInfo`1"/> argument,
which describes the change.
<para/>
The event handler is not allowed to modify the list that is changing
while it is handling the event, but it can read the list.
<para/>
IMPORTANT: if the event handler throws an exception, the change does
not actually happen. Collections that support this event must ensure
that the collection is not left in an invalid state in the event that
a ListChanging event handler throws an exception.
</remarks>
</member>
<member name="T:Loyc.Collections.ListChangingHandler`1">
<summary>Represents the method that handles the
<see cref="E:Loyc.Collections.INotifyListChanging`1.ListChanging"/> event.</summary>
<param name="sender">The collection that changed.</param>
<param name="args">Information about the change.</param>
</member>
<member name="T:Loyc.Collections.DList`1">
<summary>
A compact auto-enlarging list that efficiently supports supports insertions
at the beginning or end of the list.
</summary>
<seealso cref="T:Loyc.Collections.Impl.InternalDList`1"/>
<seealso cref="T:Loyc.Collections.DList"/>
</member>
<member name="M:Loyc.Collections.DList`1.Add(`0)">
<summary>An alias for PushLast().</summary>
</member>
<member name="T:Loyc.Collections.DList">
<summary>
This class is the same as <see cref="!:DList<object>"/> except that it
also implements the IList interface.
</summary>
</member>
<member name="T:Loyc.Collections.BufferedSequence`1">
<summary>This class wraps an <see cref="T:System.Collections.Generic.IEnumerator`1"/> or
<see cref="T:System.Collections.Generic.IEnumerable`1"/> into an <see cref="!:IListSource"/>, lazily
reading the sequence as <see cref="M:Loyc.Collections.BufferedSequence`1.TryGet(System.Int32,System.Boolean@)"/> is called.</summary>
<remarks>Avoid calling <see cref="P:Loyc.Collections.BufferedSequence`1.Count"/> if you actually want laziness;
this property must read and buffer the entire sequence.</remarks>
</member>
</members>
</doc>
Submit an article or tip