=begin
= GSL::Vector class

== Class methods

--- GSL::Vector.alloc(ary) 
--- GSL::Vector.new(ary) 
--- GSL::Vector.new(range) 
--- GSL::Vector.new(size) 
--- GSL::Vector.new(n, [xmin, xmax])
--- GSL::Vector.new(elm0, elm1, ....) 
    These methods create a (({GSL::Vector})) object. This example 
    initializes a vector of length 10,
      require('gsl')
      v = Vector.new(10)         ( or use 'alloc' )
    Vector elements will be set with the 'set' method.

    One can create a vector by giving an array, as
      v = Vector.new([1, 2, 3])
    or with a range object,
      v = Vector.new(1..3)

--- GSL::Vector.GSL::Vector.calloc(size)
    This method also creates a vector object, and initializes all the elements to zero.
=== NArray Extension
If a (({NArray})) object is given, a newly allocated vector is created.

ex)
        na = NArray[1.0, 2, 3, 4, 5]
        p na                <----- NArray.float(5): 
                                   [ 1.0, 2.0, 3.0, 4.0, 5.0]
        v = Vector.new(na)  
        p v                 <----- [ 1 2 3 4 5 ]
                                   #<GSL::Vector:0x367ff4>

== NOTE:
In Ruby/GSL, vector lendth is limited within the range of Fixnum.
For 32-bit CPU, the maximum of vector length is 2^30 ~ 1e9.

== Methods

--- GSL::Vector#get(i)
    This returns the ((|i|))-th element of the vector ((|self|)). The method '[]' 
    is also available.

--- GSL::Vector#set(i, val)
    This method sets the ((|i|))-th element of the vector ((|self|)) to ((|val|)).
      ex) v.set(2, 3.5)      # v[2] = 3.5

--- GSL::Vector#set_all(x)
    This method sets all the elements of the vector to the value ((|x|)).

--- GSL::Vector#set_zero
    This method sets all the elements of the vector to zero.

--- GSL::Vector#set_basis!(i)
    This method makes a basis vector by setting all the elements of the vector
    to zero except for the ((|i|))-th element, which is set to one. For a vector v of
    the size 10, the method
      v.set_basis!(4)
    sets the vector ((|self|)) to a basis vector [0, 0, 0, 0, 1, 0, 0, 0, 0, 0]. 
    The vector ((|self|)) is modified.

--- GSL::Vector#set_basis(i)
    This method returns a basis vector by setting all the elements of the vector
    to zero except for the i-th element which is set to one. For a vector v of
    the size 10, the method
      vb = v.set_basis(4)
    creates a new vector ((|self|)) with elements [0, 0, 0, 0, 1, 0, 0, 0, 0, 0]. 
    The vector ((|self|)) is not changed.

--- GSL::Vector#each
    Iterator for each vector element, used as
      v.each do |x|
        p x
      end

--- GSL::Vector#each_index
    Another iterator, as the one of Ruby Array.

=== IO
--- GSL::Vector#print
    Show all the elements of the vector in %4.3e format.

--- GSL::Vector#fprintf(io, format = "%e")
--- GSL::Vector#fprintf(filename, format = "%e")
--- GSL::Vector#fscanf(io)
--- GSL::Vector#fscanf(filename)
--- GSL::Vector#fwrite(io)
--- GSL::Vector#fwrite(filename)
--- GSL::Vector#fread(io)
--- GSL::Vector#fread(filename)
    Methods for writing or reading the vector. The first argument is IO or String object.

--- GSL::Vector#clone
    This method creates a new vector of the same elements.

--- GSL::Vector#swap_elements(i, j)
    This method exchanges the i-th and j-th elements of the vector in-place. 

--- GSL::Vector#reverse
--- GSL::Vector#reverse!
    These methods reverse the order of the elements of the vector.

=== Vector views
The (({GSL::Vector::View})) class is defined to be used as "references" to
the vectors. Since the (({Vector::View})) class is a subclass of the class (({Vector})),
an instance of the (({View})) class created by slicing a (({Vector})) object 
can be used same as the original vector. The
(({View})) object shares the data with the original vector, i.e. changes
in the elements of the (({View})) object affect to the original.

--- GSL::Vector#subvector(offset, n)
--- GSL::Vector#subvector(n)
--- GSL::Vector#subvector
    This method creates a (({Vector::View})) object slicing ((|n|)) elements
    of the vector ((|self|)) from the offset ((|offset|)). If called with only one
    argument ((|n|)), ((|offset|)) is set to 0. With no arguments, a view is
    created with the same length of the original vector.

    * ex:
       #!/usr/bin/env ruby
       require("gsl")

       v = Vector.new([1, 2, 3, 4, 5, 6])
       view = v.subvector(1, 4)
       p view.class         <----- GSL::Vector::View
       view.print           <----- [ 2 3 4 5 ]

       view[2] = 99
       view.print           <----- [ 2 3 99 5 ]
       v.print              <----- [ 1 2 3 99 5 6 ]

--- GSL::Vector#subvector_with_stride(offset, n, stride)

--- GSL::Vectir#matrix_view(n1, n2)
    This creates a (({Matrix::View})) object from the vector ((|self|)).
    It enables to use the vector as a ((<Matrix|URL:matrix.html>)) object.
    * ex:
       v2 = Vector.new([1, 2, 3, 4, 5, 6, 7, 8, 9])
       mview = v2.matrix_view(3, 3)
       p mview.class            <----- GSL::Matrix::View
       mview.print              <----- [ 1 2 3 
                                         4 5 6 
                                         7 8 9 ]
       mview.set(2, 1, 99.9)
       mview.print              <----- [ 1 2 3 
                                         4 5 6 
                                         7 99.9 9 ]
       v2.print                 
           <----- [ 1 2 3 4 5 6 7 99.9 9 ]


=== Vector operations

--- GSL::Vector#trans
--- GSL::Vector#transpose
--- GSL::Vector#col
--- GSL::Vector#row
    Transpose the vector to a column or a row vector.

--- GSL::Vector#add!(b)
--- GSL::Vector#+=(b)
    This method adds the elements of vector b to the elements of vector ((|self|)).
    The vector ((|self|)) is modified in place.
    The two vectors must have the same length. 

--- GSL::Vector#add(b)
--- GSL::Vector#*(b)
    This method adds the elements of vector b to the elements of the vector ((|self|)),
    and returns a new vector. The vector ((|self|)) is not changed.

--- GSL::Vector#sub!(b)
--- GSL::Vector#-=(b)
    This method subtracts the elements of vector b from the elements of vector ((|self|)).
    The two vectors must have the same length. The vector ((|self|)) is modified in place.

--- GSL::Vector#sub(b)
--- GSL::Vector#-(b)
    Same as GSL::Vector#sub!(b), but not modifies the vector itself, 
    and returns a new vector.

--- GSL::Vector#div!(b)
--- GSL::Vector#/=(b)
    This method divides the elements of vector ((|self|)) by the elements of vector b. 
    The two vectors must have the same length. The vector ((|self|)) is modified.

--- GSL::Vector#div(b)
--- GSL::Vector#/(b)
    Same as GSL::Vector#div!(b), but not modifies the vector ((|self|)), 
    and returns a new vector.

--- GSL::Vector#mul(b)
--- GSL::Vector#*(b)
    Vector multiplication.

    * ex1: Scale
        irb(main):027:0> v = Vector.new(1, 2)
        [ 1 2 ]
        => #<GSL::Vector:0x77a8d0>
        irb(main):028:0> v*2
        [ 2 4 ]                           
        => #<GSL::Vector:0x7794e4>
    * ex2: Element-by-element multiplication
        irb(main):018:0> a = Vector.new(1, 2); b = Vector.new(3, 4)
        [ 3 4 ]
        => #<GSL::Vector:0x78f500>
        irb(main):020:0> a*b
        [ 3 8 ]                             
        => #<GSL::Vector:0x78e074>
    * ex3: Inner product
        irb(main):023:0> a = Vector.new(1, 2); b = Vector::Col.new(3, 4)
        [ 3 
          4 ]
        => #<GSL::Vector::Col:0x7840c4>
        irb(main):024:0> a*b
        => 11.0                        
    * ex4: Vector::Col*Vector -> Matrix
        irb(main):025:0> a = Vector::Col.new(1, 2); b = Vector.new(3, 4)
        [ 3 4 ]
        => #<GSL::Vector:0x77e458>
        irb(main):026:0> a*b
        [ 3 4 
          6 8 ]
        => #<GSL::Matrix:0x77cfcc>
    * ex5: Matrix*Vector::Col -> Vector::Col
        irb(main):029:0> a = Vector.new(1, 2); m = Matrix.new([2, 3], [4, 5])
        [ 2 3 
          4 5 ]
        => #<GSL::Matrix:0x774160>
        irb(main):030:0> m*a          <--- Error
        TypeError: Operation with GSL::Vector is not defined (GSL::Vector::Col expected)
                from (irb):30:in `*'
                from (irb):30
        irb(main):031:0> m*a.col
        [ 8 
          14 ]
        => #<GSL::Vector::Col:0x771230>

--- GSL::Vector#scale!(x)
--- GSL::Vector#scale(x)
    This method multiplies the elements of vector ((|self|)) by 
    the constant factor x.

--- GSL::Vector#add_constant!(x)
--- GSL::Vector#add_constant(x)
    This method adds the constant value x to the elements of the vector ((|self|)).

--- GSL::Vector#reverse
--- GSL::Vector#swap_elements

--- GSL::Vector#clone
    This creates a copy of the vector ((|self|)).

=== Finding maximum and minimum elements of vectors

--- GSL::Vector#max
    This method returns the maximum value in the vector.

--- GSL::Vector#min
    This method returns the minimum value in the vector.

--- GSL::Vector#minmax
    This method returns an array of two elements, the minimum and the maximum values
    in the vector ((|self|)).

--- GSL::Vector#max_index
    This method returns the index of the maximum value in the vector. When there are 
    several equal maximum elements then the lowest index is returned. 

--- GSL::Vector#min_index
    This method returns the index of the minimum value in the vector. When there are 
    several equal minimum elements then the lowest index is returned. 

--- GSL::Vector#minmax_index
    This method returns an array of two elements which has the indices of the minimum 
    and the maximum values in the vector ((|self|)).

=== Vector Properties
--- GSL::Vector#isnull
    This method returns 1 if all the elements of the vector ((|self|)) 
    are zero, and 0 otherwise.
--- GSL::Vector#isnull?
    This method returns (({true})) if all the elements of the vector ((|self|)) 
    are zero, and (({false})) otherwise.

--- GSL::Vector#to_a 
    This method converts the vector into a Ruby array. A Ruby array also can be
    converted into a GSL::Vector object with the (({to_gv})) method. For example,
      v = GSL::Vector.alloc([1, 2, 3, 4, 5])
      a = v.to_a   -> GSL::Vector to an array
      p a          -> [1.0, 2.0, 3.0, 4.0, 5.0]
      a[2] = 12.0
      v2 = a.to_gv  -> a new GSL::Vector object
      v2.print     -> 1.0000e+00 2.0000e+00 1.2000e+01 4.0000e+00 5.0000e+00

== NArray 

--- GSL::Vector#to_na
    The Vector object ((|self|)) is converted into an NArray object. The array 
    data are copied to newly allocated memory.

--- GSL::Vector.na_to_gv(na)
--- GSL::Vector.na_to_gslv(na)
--- GSL::Vector.to_gv(na)
--- GSL::Vector.to_gslv(na)
    A (({GSL::Vector::View})) object is created from the NArray object ((|na|)). 
    The data of ((|na|)) are 
    not copied, thus any modifications to the View object affect on the original 
    NArray object. The View object can be used as a reference to the NArray object.

((<back|URL:index.html>))
=end
