Added typed (BLAS-like) API code examples.

Details:
- Added new example code to examples/tapi demonstrating how to use the
  BLIS typed API. These code examples directly mirror the corresponding
  example code files in examples/oapi. This setup provides a convenient
  opportunity for newcomers to BLIS to compare and contrast the typed
  and object APIs when they are used to perform the same tasks.
- Minor cleanups to examples/oapi.

examples/oapi/00obj_basic.c

@@ -43,11 +43,13 @@ int main( int argc, char** argv )
 	dim_t m, n;
 	inc_t rs, cs;
 
+
 	//
 	// This file demonstrates the basics of creating objects in BLIS,
 	// inspecting their basic properties, and printing matrix objects.
 	//
 
+
 	//
 	// Example 1: Create an object containing a 4x3 matrix of double-
 	//            precision real elements stored in column-major order.
@@ -69,6 +71,7 @@ int main( int argc, char** argv )
 	                  rs = 1; cs = 6; 
 	bli_obj_create( dt, m, n, rs, cs, &a2 );
 
+
 	//
 	// Example 2: Create an object containing a 4x3 matrix of double-
 	//            precision real elements stored in row-major order.
@@ -87,6 +90,7 @@ int main( int argc, char** argv )
 	                  rs = 8; cs = 1; 
 	bli_obj_create( dt, m, n, rs, cs, &a4 );
 
+
 	//
 	// Example 3: Create objects using other floating-point datatypes.
 	//
@@ -98,6 +102,7 @@ int main( int argc, char** argv )
 	bli_obj_create( BLIS_SCOMPLEX, m, n, rs, cs, &a6 );
 	bli_obj_create( BLIS_DCOMPLEX, m, n, rs, cs, &a7 );
 
+
 	//
 	// Example 4: Create objects using default (column) storage so that
 	//            we avoid having to specify rs and cs manually.
@@ -112,6 +117,7 @@ int main( int argc, char** argv )
 	// in doubt, query the value! 
 	bli_obj_create( BLIS_FLOAT, 3, 5, 0, 0, &a8 );
 
+
 	//
 	// Example 5: Inspect object fields after creation to expose
 	//            possible alignment/padding.
@@ -128,6 +134,7 @@ int main( int argc, char** argv )
 	printf( "row stride:         %d\n", ( int )bli_obj_row_stride( &a8 ) );
 	printf( "col stride:         %d\n", ( int )bli_obj_col_stride( &a8 ) );
 
+
 	//
 	// Example 6: Inspect object fields after creation of other floating-
 	//            point datatypes.
@@ -162,6 +169,7 @@ int main( int argc, char** argv )
 	printf( "row stride:         %d\n", ( int )bli_obj_row_stride( &a11 ) );
 	printf( "col stride:         %d\n", ( int )bli_obj_col_stride( &a11 ) );
 
+
 	//
 	// Example 7: Initialize an object's elements to random values and then
 	//            print the matrix.
@@ -181,6 +189,7 @@ int main( int argc, char** argv )
 	// elements of type 'float'.
 	bli_printm( "matrix 'a9' contents:", &a9, "%4.1f", "" );
 
+
 	//
 	// Example 8: Randomize and then print from an object containing a complex
 	//            matrix.
@@ -193,13 +202,14 @@ int main( int argc, char** argv )
 	bli_randm( &a11 );
 	bli_printm( "matrix 'a11' contents (complex):", &a11, "%4.1f", "" );
 
+
 	//
 	// Example 9: Create, randomize, and print vector objects.
 	//
 
 	printf( "\n#\n#  -- Example 9 --\n#\n\n" );
 
-	// Now let's create two vector object--a row vector and a column vector.
+	// Now let's create two vector objects--a row vector and a column vector.
 	// (A vector object is like a matrix object, except that it has at least
 	// one unit dimension (equal to one).
 	bli_obj_create( BLIS_DOUBLE, 4, 1, 0, 0, &v1 );

examples/oapi/01obj_attach.c

@@ -46,11 +46,13 @@ int main( int argc, char** argv )
 	dim_t m, n;
 	inc_t rs, cs;
 
+
 	//
 	// This file demonstrates interfacing external or existing buffers
 	// with BLIS objects.
 	//
 
+
 	//
 	// Example 1: Create a bufferless object and then attach an external
 	//            buffer to it, specifying column storage.
@@ -86,6 +88,7 @@ int main( int argc, char** argv )
 	// assigned.
 	bli_printm( "matrix 'a1', initialized by columns:", &a1, "%5.1f", "" );
 
+
 	//
 	// Example 2: Create a bufferless object and then attach an external
 	//            buffer to it, specifying row storage.

examples/oapi/02obj_ij.c

@@ -49,11 +49,13 @@ int main( int argc, char** argv )
 	inc_t rs, cs;
 	dim_t i, j;
 
+
 	//
 	// This file demonstrates accessing and updating individual matrix elements
 	// through the BLIS object API.
 	//
 
+
 	//
 	// Example 1: Create an object and then individually access/view some of
 	//            its elements.
@@ -98,6 +100,7 @@ int main( int argc, char** argv )
 
 	printf( "\n" );
 
+
 	//
 	// Example 2: Modify individual elements of an existing matrix.
 	//
@@ -132,6 +135,7 @@ int main( int argc, char** argv )
 	// it should contain the same initial state as a1.
 	bli_printm( "matrix 'a2'", &a2, "%5.1f", "" );
 
+
 	//
 	// Example 3: Modify individual elements of an existing complex matrix.
 	//

examples/oapi/03obj_view.c

@@ -51,10 +51,12 @@ int main( int argc, char** argv )
 	dim_t i, j;
 	dim_t mv, nv;
 
+
 	//
 	// This file demonstrates creating and submatrix views into existing matrices.
 	//
 
+
 	//
 	// Example 1: Create an object and then create a submatrix view.
 	//
@@ -85,6 +87,7 @@ int main( int argc, char** argv )
 	// bli_obj_create(). In the above example, that means only object a1
 	// would be passed to bli_obj_free().
 
+
 	//
 	// Example 2: Modify the contents of a submatrix view.
 	//
@@ -105,6 +108,7 @@ int main( int argc, char** argv )
 	bli_printm( "submatrix view 'v1' (modified state)", &v1, "%5.1f", "" );
 	bli_printm( "matrix 'a1' (indirectly modified due to changes to 'v1')", &a1, "%5.1f", "" );
 
+
 	//
 	// Example 3: Create a submatrix view that is "too big".
 	//
@@ -125,6 +129,7 @@ int main( int argc, char** argv )
 
 	bli_printm( "4x3 submatrix 'v2' at offsets (4,2) -- two rows truncated for safety", &v2, "%5.1f", "" );
 
+
 	//
 	// Example 4: Create a bufferless object, attach an external buffer, and
 	//            then create a submatrix view.
@@ -145,6 +150,7 @@ int main( int argc, char** argv )
 
 	bli_printm( "3x4 submatrix view 'v3' at offsets (2,3)", &v3, "%5.1f", "" );
 
+
 	//
 	// Example 5: Use a submatrix view to set a region of a larger matrix to
 	//            zero.
@@ -160,6 +166,7 @@ int main( int argc, char** argv )
 
 	bli_printm( "matrix 'a2' (modified state)", &a2, "%5.1f", "" );
 
+
 	//
 	// Example 6: Obtain a submatrix view into a submatrix view.
 	//

examples/oapi/04level0.c

@@ -41,10 +41,12 @@ int main( int argc, char** argv )
 	num_t dt;
 	double gamma_d;
 
+
 	//
 	// This file demonstrates working with scalar objects.
 	//
 
+
 	//
 	// Example 1: Create a scalar (1x1) object.
 	//
@@ -85,6 +87,7 @@ int main( int argc, char** argv )
 	// update their values, though you can always perform operations *with*
 	// them--that's the whole point!).
 
+
 	//
 	// Example 2: Set the value of an existing scalar object.
 	//
@@ -107,6 +110,7 @@ int main( int argc, char** argv )
 	bli_printm( "kappa:", &kappa, "%4.1f", "" );
 	bli_printm( "gamma:", &gamma, "%4.1f", "" );
 
+
 	//
 	// Example 3: Create and set the value of a complex scalar object.
 	//
@@ -119,6 +123,7 @@ int main( int argc, char** argv )
 	bli_setsc( 3.3, -4.4, &zeta );
 	bli_printm( "zeta (complex):", &zeta, "%4.1f", "" );
 
+
 	//
 	// Example 4: Copy scalar objects.
 	//
@@ -133,6 +138,7 @@ int main( int argc, char** argv )
 	bli_copysc( &BLIS_ONE, &gamma );
 	bli_printm( "gamma (overwritten with BLIS_ONE):", &gamma, "%4.1f", "" );
 
+
 	//
 	// Example 5: Perform other operations on scalar objects.
 	//

examples/oapi/05level1v.c

@@ -43,11 +43,13 @@ int main( int argc, char** argv )
 	dim_t m, n;
 	inc_t rs, cs;
 
+
 	//
 	// This file demonstrates working with vector objects and the level-1v
 	// operations.
 	//
 
+
 	//
 	// Example 1: Create vector objects and then broadcast (copy) scalar
 	//            values to all elements.
@@ -95,6 +97,7 @@ int main( int argc, char** argv )
 	bli_printm( "y := alpha", &y, "%4.1f", "" );
 	bli_printm( "z := 0.0", &z, "%4.1f", "" );
 
+
 	//
 	// Example 2: Randomize a vector object.
 	//
@@ -106,6 +109,7 @@ int main( int argc, char** argv )
 
 	bli_printm( "w := randv()", &w, "%4.1f", "" );
 
+
 	//
 	// Example 3: Perform various element-wise operations on vector objects.
 	//
@@ -147,6 +151,7 @@ int main( int argc, char** argv )
 	bli_printm( "x (after swapping with y)", &x, "%4.1f", "" );
 	bli_printm( "y (after swapping with x)", &y, "%4.1f", "" );
 
+
 	//
 	// Example 4: Perform contraction-like operations on vector objects.
 	//

examples/oapi/06level1m.c

@@ -43,11 +43,13 @@ int main( int argc, char** argv )
 	dim_t m, n;
 	inc_t rs, cs;
 
+
 	//
 	// This file demonstrates working with matrix objects and the level-1m
 	// operations.
 	//
 
+
 	//
 	// Example 1: Create matrix objects and then broadcast (copy) scalar
 	//            values to all elements.
@@ -88,6 +90,7 @@ int main( int argc, char** argv )
 	bli_printm( "b := alpha", &b, "%4.1f", "" );
 	bli_printm( "c := 0.0", &c, "%4.1f", "" );
 
+
 	//
 	// Example 2: Randomize a matrix object.
 	//
@@ -99,6 +102,7 @@ int main( int argc, char** argv )
 
 	bli_printm( "e (randomized):", &e, "%4.1f", "" );
 
+
 	//
 	// Example 3: Perform element-wise operations on matrices.
 	//
@@ -128,6 +132,7 @@ int main( int argc, char** argv )
 	bli_axpym( &alpha, &a, &c );
 	bli_printm( "c := c + alpha * a", &c, "%4.1f", "" );
 
+
 	//
 	// Example 4: Copy and transpose a matrix.
 	//
@@ -170,6 +175,7 @@ int main( int argc, char** argv )
 
 	bli_printm( "f (copied value):", &f, "%4.1f", "" );
 
+
 	//
 	// Example 5: Copy and Hermitian-transpose a matrix.
 	//

examples/oapi/07level1m_diag.c

@@ -41,10 +41,12 @@ int main( int argc, char** argv )
 	dim_t m, n;
 	inc_t rs, cs;
 
+
 	//
 	// This file demonstrates level-1m operations on structured matrices.
 	//
 
+
 	//
 	// Example 1: Initialize the upper triangle of a matrix to random values.
 	//
@@ -221,6 +223,7 @@ int main( int argc, char** argv )
 
 	bli_printm( "d: transpose of lower triangular of bl copied to d", &d, "%4.1f", "" );
 
+
 	//
 	// Example 5: Create a rectangular matrix (m > n) with a lower trapezoid
 	//            containing random values, then set the strictly upper
@@ -267,6 +270,7 @@ int main( int argc, char** argv )
 
 	bli_printm( "e: after upper triangle set to zero", &e, "%4.1f", "" );
 
+
 	//
 	// Example 6: Create an upper Hessenberg matrix of random values and then
 	//            set the "unstored" values to zero.
@@ -318,6 +322,7 @@ int main( int argc, char** argv )
 	bli_obj_free( &c );
 	bli_obj_free( &d );
 	bli_obj_free( &e );
+	bli_obj_free( &h );
 
 	return 0;
 }

examples/oapi/08level2.c

@@ -45,10 +45,12 @@ int main( int argc, char** argv )
 	obj_t* alpha;
 	obj_t* beta;
 
+
 	//
 	// This file demonstrates level-2 operations.
 	//
 
+
 	//
 	// Example 1: Perform a general rank-1 update (ger) operation.
 	//
@@ -86,6 +88,7 @@ int main( int argc, char** argv )
 	bli_obj_free( &x );
 	bli_obj_free( &y );
 
+
 	//
 	// Example 2: Perform a general matrix-vector multiply (gemv) operation.
 	//
@@ -133,6 +136,7 @@ int main( int argc, char** argv )
 	bli_obj_free( &x );
 	bli_obj_free( &y );
 
+
 	//
 	// Example 3: Perform a symmetric rank-1 update (syr) operation.
 	//
@@ -173,6 +177,7 @@ int main( int argc, char** argv )
 	bli_obj_free( &a );
 	bli_obj_free( &x );
 
+
 	//
 	// Example 4: Perform a symmetric matrix-vector multiply (symv) operation.
 	//
@@ -218,6 +223,7 @@ int main( int argc, char** argv )
 	bli_obj_free( &x );
 	bli_obj_free( &y );
 
+
 	//
 	// Example 5: Perform a triangular matrix-vector multiply (trmv) operation.
 	//
@@ -258,6 +264,7 @@ int main( int argc, char** argv )
 	bli_obj_free( &a );
 	bli_obj_free( &x );
 
+
 	//
 	// Example 6: Perform a triangular solve (trsv) operation.
 	//

examples/oapi/09level3.c

@@ -43,14 +43,15 @@ int main( int argc, char** argv )
 	side_t side;
 
 	obj_t a, b, c, d;
-	obj_t aa, bb, cc;
 	obj_t* alpha;
 	obj_t* beta;
 
+
 	//
 	// This file demonstrates level-3 operations.
 	//
 
+
 	//
 	// Example 1: Perform a general matrix-matrix multiply (gemm) operation.
 	//
@@ -87,6 +88,7 @@ int main( int argc, char** argv )
 	bli_obj_free( &b );
 	bli_obj_free( &c );
 
+
 	//
 	// Example 1b: Perform a general matrix-matrix multiply (gemm) operation
 	//             with the left input operand (matrix A) transposed.
@@ -97,35 +99,36 @@ int main( int argc, char** argv )
 	// Create some matrix operands to work with.
 	dt = BLIS_DOUBLE;
 	m = 4; n = 5; k = 3; rs = 0; cs = 0;
-	bli_obj_create( dt, m, n, rs, cs, &cc );
-	bli_obj_create( dt, k, m, rs, cs, &aa );
-	bli_obj_create( dt, k, n, rs, cs, &bb );
+	bli_obj_create( dt, m, n, rs, cs, &c );
+	bli_obj_create( dt, k, m, rs, cs, &a );
+	bli_obj_create( dt, k, n, rs, cs, &b );
 
 	// Set the scalars to use.
 	alpha = &BLIS_ONE;
 	beta  = &BLIS_ONE;
 
 	// Initialize the matrix operands.
-	bli_randm( &aa );
-	bli_setm( &BLIS_ONE, &bb );
-	bli_setm( &BLIS_ZERO, &cc );
+	bli_randm( &a );
+	bli_setm( &BLIS_ONE, &b );
+	bli_setm( &BLIS_ZERO, &c );
 
-	// Set the transpose bit in 'aa'.
-	bli_obj_toggle_trans( &aa );
+	// Set the transpose bit in 'a'.
+	bli_obj_toggle_trans( &a );
 
-	bli_printm( "a: randomized", &aa, "%4.1f", "" );
-	bli_printm( "b: set to 1.0", &bb, "%4.1f", "" );
-	bli_printm( "c: initial value", &cc, "%4.1f", "" );
+	bli_printm( "a: randomized", &a, "%4.1f", "" );
+	bli_printm( "b: set to 1.0", &b, "%4.1f", "" );
+	bli_printm( "c: initial value", &c, "%4.1f", "" );
 
 	// c := beta * c + alpha * a^T * b, where 'a', 'b', and 'c' are general.
-	bli_gemm( alpha, &aa, &bb, beta, &cc );
+	bli_gemm( alpha, &a, &b, beta, &c );
 
-	bli_printm( "c: after gemm", &cc, "%4.1f", "" );
+	bli_printm( "c: after gemm", &c, "%4.1f", "" );
 
 	// Free the objects.
-	bli_obj_free( &aa );
-	bli_obj_free( &bb );
-	bli_obj_free( &cc );
+	bli_obj_free( &a );
+	bli_obj_free( &b );
+	bli_obj_free( &c );
+
 
 	//
 	// Example 2: Perform a symmetric rank-k update (syrk) operation.
@@ -164,6 +167,7 @@ int main( int argc, char** argv )
 	bli_obj_free( &c );
 	bli_obj_free( &a );
 
+
 	//
 	// Example 3: Perform a symmetric matrix-matrix multiply (symm) operation.
 	//
@@ -214,6 +218,7 @@ int main( int argc, char** argv )
 	bli_obj_free( &b );
 	bli_obj_free( &c );
 
+
 	//
 	// Example 4: Perform a triangular matrix-matrix multiply (trmm) operation.
 	//
@@ -251,12 +256,13 @@ int main( int argc, char** argv )
 	// b := alpha * a * b, where 'a' is triangular and lower-stored.
 	bli_trmm( side, alpha, &a, &b );
 
-	bli_printm( "x: after trmv", &b, "%4.1f", "" );
+	bli_printm( "x: after trmm", &b, "%4.1f", "" );
 
 	// Free the objects.
 	bli_obj_free( &a );
 	bli_obj_free( &b );
 
+
 	//
 	// Example 5: Perform a triangular solve with multiple right-hand sides
 	//            (trsm) operation.

examples/oapi/10util.c

@@ -43,11 +43,13 @@ int main( int argc, char** argv )
 	dim_t m, n;
 	inc_t rs, cs;
 
+
 	//
 	// This file demonstrates working with vector and matrix objects in the
 	// context of various utility operations.
 	//
 
+
 	//
 	// Example 1: Compute various vector norms.
 	//
@@ -73,7 +75,7 @@ int main( int argc, char** argv )
 
 	bli_printm( "x:", &x, "%4.1f", "" );
 
-	// Compute the one-norm of 'x'.
+	// Compute the one, infinity, and frobenius norms of 'x'.
 	bli_norm1v( &x, &norm1 );
 	bli_normiv( &x, &normi );
 	bli_normfv( &x, &normf );
@@ -84,9 +86,9 @@ int main( int argc, char** argv )
 
 	bli_printm( "y:", &y, "%4.1f", "" );
 
-	// Compute the one-norm of 'y'. Note that we can reuse the same scalars
-	// from before for computing norms of dcomplex matrices, since the real
-	// projection of dcomplex is double.
+	// Compute the one, infinity, and frobenius norms of 'y'. Note that we
+	// can reuse the same scalars from before for computing norms of
+	// dcomplex matrices, since the real projection of dcomplex is double.
 	bli_norm1v( &y, &norm1 );
 	bli_normiv( &y, &normi );
 	bli_normfv( &y, &normf );
@@ -95,6 +97,7 @@ int main( int argc, char** argv )
 	bli_printm( "y: infinity norm:", &normi, "%4.1f", "" );
 	bli_printm( "y: frobenius norm:", &normf, "%4.1f", "" );
 
+
 	//
 	// Example 2: Compute various matrix norms.
 	//
@@ -132,6 +135,7 @@ int main( int argc, char** argv )
 	bli_printm( "b: infinity norm:", &normi, "%4.1f", "" );
 	bli_printm( "b: frobenius norm:", &normf, "%4.1f", "" );
 
+
 	//
 	// Example 3: Make a real matrix explicitly symmetric (or Hermitian).
 	//
@@ -159,7 +163,7 @@ int main( int argc, char** argv )
 	// unstored triangle, making the matrix densely symmetric.
 	bli_mksymm( &c );
 
-	bli_printm( "c (after mksymm):", &c, "%4.1f", "" );
+	bli_printm( "c (after mksymm on lower triangle):", &c, "%4.1f", "" );
 
 	// Digression: Most people think only of complex matrices as being able
 	// to be complex. However, in BLIS, we define Hermitian operations on
@@ -182,11 +186,8 @@ int main( int argc, char** argv )
 	// imaginary elements to conjugate.
 	bli_mkherm( &d );
 
-	bli_printm( "d (after mkherm):", &d, "%4.1f", "" );
+	bli_printm( "d (after mkherm on lower triangle):", &d, "%4.1f", "" );
 
-	// Set the structure and uplo of 'd'.
-	bli_obj_set_struc( BLIS_HERMITIAN, &d );
-	bli_obj_set_uplo( BLIS_LOWER, &d );
 
 	//
 	// Example 4: Make a complex matrix explicitly symmetric or Hermitian.
@@ -235,6 +236,7 @@ int main( int argc, char** argv )
 
 	bli_printm( "f (after mkherm):", &f, "%4.1f", "" );
 
+
 	//
 	// Example 5: Make a real matrix explicitly triangular.
 	//