Rescaling a general size matrix

Multiplying or dividing a matrix by a scalar value follows the scheme of the above copy, addition and subtraction operations. To multiply a matrix $A$ by a scalar $s$, $B=sA$, use for example

      Gan_Matrix mA, mB; /* declare matrices A & B */

      /* ... create & fill mA, create (& optionally fill) mB ... */
      gan_mat_scale_q ( &mA, 5.0, &mB ); /* B = 5*A */

to multiply all the elements in matrix $A$ by five, writing the result into matrix $B$. Alternatively you can create the rescaled matrix from scratch as in

      Gan_Matrix *pmB; /* declare matrix B */

      /* ... create & fill mA ... */
      pmB = gan_mat_scale_s ( &mA, 5.0 ); /* B = 5*A */

or overwrite $A$ with the result

      gan_mat_scale_i ( &mA, 5.0 ); /* replace A = 5*A */

There are similar routines for dividing a general size matrix by a scalar value:

      gan_mat_divide_q ( &mA, 5.0, &mB ); /* B = A/5 */
      pmB = gan_mat_divide_s ( &mA, 5.0 ); /* B = A/5 */
      gan_mat_divide_i ( &mA, 5.0 ); /* replace A = A/5 */

There are specific routines to negate a matrix, i.e. multiply it by -1, as follows:

      gan_mat_negate_q ( &mA, &mB ); /* B = -A */
      pmB = gan_mat_negate_s ( &mA ); /* B = -A */
      gan_mat_negate_i ( &mA ); /* replace A = -A */

The equivalent routines for square matrices are

      Gan_SquMatrix smA, smB, *psmB; /* declare matrices A & B */

      /* ... create & fill smA, create (& optionally fill) smB ... */

      /* scale a square matrix */
      gan_squmat_scale_q ( &smA, 5.0, &smB ); /* B = 5*A, B an existing matrixOR */
      psmB = gan_squmat_scale_s ( &smA, 5.0 ); /* B = 5*A, B a new matrix, OR */
      gan_squmat_scale_i ( &smA, 5.0 ); /* replace A = 5*A */

      /* divide a square matrix by a scalar */
      gan_squmat_divide_q ( &smA, 5.0, &smB ); /* B = A/5, B an existing matrix, OR */
      psmB = gan_squmat_divide_s ( &smA, 5.0 ); /* B = A/5, B a new matrix, OR */
      gan_squmat_divide_i ( &smA, 5.0 ); /* replace A = A/5 */

      /* negate a square matrix */
      gan_squmat_negate_q ( &smA, &smB ); /* B = -A, B an existing matrix, OR */
      psmB = gan_squmat_negate_s ( &smA ); /* B = -A, B a new matrix, OR */
      gan_squmat_negate_i ( &smA ); /* replace A = -A */

Passing zero as the scalar value to the gan_mat_divide_[qsi]() or gan_squmat_divide_[qsi]() routines invokes the error handler, with a division by zero error (error code GAN_ERROR_DIVISION_BY_ZERO), and NULL is returned.

Error detection: The Gandalf error handler is invoked and NULL is returned if an error occurs. The most likely failure modes are (i) failing to create the result matrix; (ii) division by zero.