mathnet-numerics/src/Numerics/LinearAlgebra/Storage/VectorStorage.cs

// <copyright file="VectorStorage.cs" company="Math.NET">
// Math.NET Numerics, part of the Math.NET Project
// http://numerics.mathdotnet.com
// http://github.com/mathnet/mathnet-numerics
// http://mathnetnumerics.codeplex.com
//
// Copyright (c) 2009-2015 Math.NET
//
// Permission is hereby granted, free of charge, to any person
// obtaining a copy of this software and associated documentation
// files (the "Software"), to deal in the Software without
// restriction, including without limitation the rights to use,
// copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the
// Software is furnished to do so, subject to the following
// conditions:
//
// The above copyright notice and this permission notice shall be
// included in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
// OTHER DEALINGS IN THE SOFTWARE.
// </copyright>

using System;
using System.Collections.Generic;
using MathNet.Numerics.Properties;

namespace MathNet.Numerics.LinearAlgebra.Storage
{
    [Serializable]
    public abstract partial class VectorStorage<T> : IEquatable<VectorStorage<T>>
        where T : struct, IEquatable<T>, IFormattable
    {
        // [ruegg] public fields are OK here

        protected static readonly T Zero = BuilderInstance<T>.Vector.Zero;
        public readonly int Length;

        protected VectorStorage(int length)
        {
            if (length <= 0)
            {
                throw new ArgumentOutOfRangeException("length", Resources.ArgumentMustBePositive);
            }

            Length = length;
        }

        /// <summary>
        /// True if the vector storage format is dense.
        /// </summary>
        public abstract bool IsDense { get; }

        /// <summary>
        /// Gets or sets the value at the given index, with range checking.
        /// </summary>
        /// <param name="index">
        /// The index of the element.
        /// </param>
        /// <value>The value to get or set.</value>
        /// <remarks>This method is ranged checked. <see cref="At(int)"/> and <see cref="At(int,T)"/>
        /// to get and set values without range checking.</remarks>
        public T this[int index]
        {
            get
            {
                ValidateRange(index);
                return At(index);
            }

            set
            {
                ValidateRange(index);
                At(index, value);
            }
        }

        /// <summary>
        /// Retrieves the requested element without range checking.
        /// </summary>
        /// <param name="index">The index of the element.</param>
        /// <returns>The requested element.</returns>
        /// <remarks>Not range-checked.</remarks>
        public abstract T At(int index);

        /// <summary>
        /// Sets the element without range checking.
        /// </summary>
        /// <param name="index">The index of the element.</param>
        /// <param name="value">The value to set the element to. </param>
        /// <remarks>WARNING: This method is not thread safe. Use "lock" with it and be sure to avoid deadlocks.</remarks>
        public abstract void At(int index, T value);

        public virtual void Clear()
        {
            for (var i = 0; i < Length; i++)
            {
                At(i, Zero);
            }
        }

        public virtual void Clear(int index, int count)
        {
            for (var i = index; i < index + count; i++)
            {
                At(i, Zero);
            }
        }

        /// <summary>
        /// Indicates whether the current object is equal to another object of the same type.
        /// </summary>
        /// <param name="other">
        /// An object to compare with this object.
        /// </param>
        /// <returns>
        /// <c>true</c> if the current object is equal to the <paramref name="other"/> parameter; otherwise, <c>false</c>.
        /// </returns>
        public virtual bool Equals(VectorStorage<T> other)
        {
            // Reject equality when the argument is null or has a different shape.
            if (other == null)
            {
                return false;
            }
            if (Length != other.Length)
            {
                return false;
            }

            // Accept if the argument is the same object as this.
            if (ReferenceEquals(this, other))
            {
                return true;
            }

            // If all else fails, perform element wise comparison.
            for (var index = 0; index < Length; index++)
            {
                if (!At(index).Equals(other.At(index)))
                {
                    return false;
                }
            }

            return true;
        }

        /// <summary>
        /// Determines whether the specified <see cref="T:System.Object"/> is equal to the current <see cref="T:System.Object"/>.
        /// </summary>
        /// <returns>
        /// true if the specified <see cref="T:System.Object"/> is equal to the current <see cref="T:System.Object"/>; otherwise, false.
        /// </returns>
        /// <param name="obj">The <see cref="T:System.Object"/> to compare with the current <see cref="T:System.Object"/>. </param>
        public override sealed bool Equals(object obj)
        {
            return Equals(obj as VectorStorage<T>);
        }

        /// <summary>
        /// Serves as a hash function for a particular type.
        /// </summary>
        /// <returns>
        /// A hash code for the current <see cref="T:System.Object"/>.
        /// </returns>
        public override int GetHashCode()
        {
            var hashNum = Math.Min(Length, 25);
            int hash = 17;
            unchecked
            {
                for (var i = 0; i < hashNum; i++)
                {
                    hash = hash*31 + At(i).GetHashCode();
                }
            }
            return hash;
        }

        // VECTOR COPY

        public void CopyTo(VectorStorage<T> target, ExistingData existingData = ExistingData.Clear)
        {
            if (target == null)
            {
                throw new ArgumentNullException("target");
            }

            if (ReferenceEquals(this, target))
            {
                return;
            }

            if (Length != target.Length)
            {
                throw new ArgumentException(Resources.ArgumentVectorsSameLength, "target");
            }

            CopyToUnchecked(target, existingData);
        }

        internal virtual void CopyToUnchecked(VectorStorage<T> target, ExistingData existingData)
        {
            for (int i = 0; i < Length; i++)
            {
                target.At(i, At(i));
            }
        }

        // ROW COPY

        public void CopyToRow(MatrixStorage<T> target, int rowIndex, ExistingData existingData = ExistingData.Clear)
        {
            if (target == null)
            {
                throw new ArgumentNullException("target");
            }

            if (Length != target.ColumnCount)
            {
                throw new ArgumentException(Resources.ArgumentVectorsSameLength, "target");
            }

            ValidateRowRange(target, rowIndex);
            CopyToRowUnchecked(target, rowIndex, existingData);
        }

        internal virtual void CopyToRowUnchecked(MatrixStorage<T> target, int rowIndex, ExistingData existingData)
        {
            for (int j = 0; j < Length; j++)
            {
                target.At(rowIndex, j, At(j));
            }
        }

        // COLUMN COPY

        public void CopyToColumn(MatrixStorage<T> target, int columnIndex, ExistingData existingData = ExistingData.Clear)
        {
            if (target == null)
            {
                throw new ArgumentNullException("target");
            }

            if (Length != target.RowCount)
            {
                throw new ArgumentException(Resources.ArgumentVectorsSameLength, "target");
            }

            ValidateColumnRange(target, columnIndex);
            CopyToColumnUnchecked(target, columnIndex, existingData);
        }

        internal virtual void CopyToColumnUnchecked(MatrixStorage<T> target, int columnIndex, ExistingData existingData)
        {
            for (int i = 0; i < Length; i++)
            {
                target.At(i, columnIndex, At(i));
            }
        }

        // SUB-VECTOR COPY

        public void CopySubVectorTo(VectorStorage<T> target,
            int sourceIndex, int targetIndex, int count,
            ExistingData existingData = ExistingData.Clear)
        {
            if (target == null)
            {
                throw new ArgumentNullException("target");
            }

            if (count == 0)
            {
                return;
            }

            ValidateSubVectorRange(target, sourceIndex, targetIndex, count);
            CopySubVectorToUnchecked(target, sourceIndex, targetIndex, count, existingData);
        }

        internal virtual void CopySubVectorToUnchecked(VectorStorage<T> target,
            int sourceIndex, int targetIndex, int count, ExistingData existingData)
        {
            if (ReferenceEquals(this, target))
            {
                var tmp = new T[count];
                for (int i = 0; i < tmp.Length; i++)
                {
                    tmp[i] = At(i + sourceIndex);
                }
                for (int i = 0; i < tmp.Length; i++)
                {
                    At(i + targetIndex, tmp[i]);
                }

                return;
            }

            for (int i = sourceIndex, ii = targetIndex; i < sourceIndex + count; i++, ii++)
            {
                target.At(ii, At(i));
            }
        }

        // SUB-ROW COPY

        public void CopyToSubRow(MatrixStorage<T> target, int rowIndex,
            int sourceColumnIndex, int targetColumnIndex, int columnCount,
            ExistingData existingData = ExistingData.Clear)
        {
            if (target == null)
            {
                throw new ArgumentNullException("target");
            }

            if (columnCount == 0)
            {
                return;
            }

            ValidateSubRowRange(target, rowIndex, sourceColumnIndex, targetColumnIndex, columnCount);
            CopyToSubRowUnchecked(target, rowIndex, sourceColumnIndex, targetColumnIndex, columnCount, existingData);
        }

        internal virtual void CopyToSubRowUnchecked(MatrixStorage<T> target, int rowIndex,
            int sourceColumnIndex, int targetColumnIndex, int columnCount, ExistingData existingData)
        {
            for (int j = sourceColumnIndex, jj = targetColumnIndex; j < sourceColumnIndex + columnCount; j++, jj++)
            {
                target.At(rowIndex, jj, At(j));
            }
        }

        // SUB-COLUMN COPY

        public void CopyToSubColumn(MatrixStorage<T> target, int columnIndex,
            int sourceRowIndex, int targetRowIndex, int rowCount,
            ExistingData existingData = ExistingData.Clear)
        {
            if (target == null)
            {
                throw new ArgumentNullException("target");
            }

            if (rowCount == 0)
            {
                return;
            }

            ValidateSubColumnRange(target, columnIndex, sourceRowIndex, targetRowIndex, rowCount);
            CopyToSubColumnUnchecked(target, columnIndex, sourceRowIndex, targetRowIndex, rowCount, existingData);
        }

        internal virtual void CopyToSubColumnUnchecked(MatrixStorage<T> target, int columnIndex,
            int sourceRowIndex, int targetRowIndex, int rowCount, ExistingData existingData)
        {
            for (int i = sourceRowIndex, ii = targetRowIndex; i < sourceRowIndex + rowCount; i++, ii++)
            {
                target.At(ii, columnIndex, At(i));
            }
        }

        // ENUMERATION

        public virtual IEnumerable<T> Enumerate()
        {
            for (var i = 0; i < Length; i++)
            {
                yield return At(i);
            }
        }

        public virtual IEnumerable<Tuple<int, T>> EnumerateIndexed()
        {
            for (var i = 0; i < Length; i++)
            {
                yield return new Tuple<int, T>(i, At(i));
            }
        }

        public virtual IEnumerable<T> EnumerateNonZero()
        {
            for (var i = 0; i < Length; i++)
            {
                var x = At(i);
                if (!Zero.Equals(x))
                {
                    yield return x;
                }
            }
        }

        public virtual IEnumerable<Tuple<int, T>> EnumerateNonZeroIndexed()
        {
            for (var i = 0; i < Length; i++)
            {
                var x = At(i);
                if (!Zero.Equals(x))
                {
                    yield return new Tuple<int, T>(i, x);
                }
            }
        }

        // FUNCTIONAL COMBINATORS

        public void MapTo<TU>(VectorStorage<TU> target, Func<T, TU> f,
            Zeros zeros = Zeros.AllowSkip, ExistingData existingData = ExistingData.Clear)
            where TU : struct, IEquatable<TU>, IFormattable
        {
            if (target == null)
            {
                throw new ArgumentNullException("target");
            }

            if (Length != target.Length)
            {
                throw new ArgumentException(Resources.ArgumentVectorsSameLength, "target");
            }

            MapToUnchecked(target, f, zeros, existingData);
        }

        internal virtual void MapToUnchecked<TU>(VectorStorage<TU> target, Func<T, TU> f, Zeros zeros, ExistingData existingData)
            where TU : struct, IEquatable<TU>, IFormattable
        {
            for (int i = 0; i < Length; i++)
            {
                target.At(i, f(At(i)));
            }
        }

        public void MapIndexedTo<TU>(VectorStorage<TU> target, Func<int, T, TU> f,
            Zeros zeros = Zeros.AllowSkip, ExistingData existingData = ExistingData.Clear)
            where TU : struct, IEquatable<TU>, IFormattable
        {
            if (target == null)
            {
                throw new ArgumentNullException("target");
            }

            if (Length != target.Length)
            {
                throw new ArgumentException(Resources.ArgumentVectorsSameLength, "target");
            }

            MapIndexedToUnchecked(target, f, zeros, existingData);
        }

        internal virtual void MapIndexedToUnchecked<TU>(VectorStorage<TU> target, Func<int, T, TU> f, Zeros zeros, ExistingData existingData)
            where TU : struct, IEquatable<TU>, IFormattable
        {
            for (int i = 0; i < Length; i++)
            {
                target.At(i, f(i, At(i)));
            }
        }

        public void Map2To(VectorStorage<T> target, VectorStorage<T> other, Func<T, T, T> f,
            Zeros zeros = Zeros.AllowSkip, ExistingData existingData = ExistingData.Clear)
        {
            if (target == null)
            {
                throw new ArgumentNullException("target");
            }

            if (other == null)
            {
                throw new ArgumentNullException("other");
            }

            if (Length != target.Length)
            {
                throw new ArgumentException(Resources.ArgumentVectorsSameLength, "target");
            }

            if (Length != other.Length)
            {
                throw new ArgumentException(Resources.ArgumentVectorsSameLength, "other");
            }

            Map2ToUnchecked(target, other, f, zeros, existingData);
        }

        internal virtual void Map2ToUnchecked(VectorStorage<T> target, VectorStorage<T> other, Func<T, T, T> f, Zeros zeros, ExistingData existingData)
        {
            for (int i = 0; i < Length; i++)
            {
                target.At(i, f(At(i), other.At(i)));
            }
        }

        public TState Fold2<TOther, TState>(VectorStorage<TOther> other, Func<TState, T, TOther, TState> f, TState state, Zeros zeros = Zeros.AllowSkip)
            where TOther : struct, IEquatable<TOther>, IFormattable
        {
            if (other == null)
            {
                throw new ArgumentNullException("other");
            }

            if (Length != other.Length)
            {
                throw new ArgumentException(Resources.ArgumentVectorsSameLength, "other");
            }

            return Fold2Unchecked(other, f, state, zeros);
        }

        internal virtual TState Fold2Unchecked<TOther, TState>(VectorStorage<TOther> other, Func<TState, T, TOther, TState> f, TState state, Zeros zeros)
            where TOther : struct, IEquatable<TOther>, IFormattable
        {
            for (int i = 0; i < Length; i++)
            {
                state = f(state, At(i), other.At(i));
            }

            return state;
        }
    }
}