os/ossrv/stdcpp/tsrc/BC/apps/widecharclassapiBCTest/src/widecharclassapiBCTestCases.cpp
author sl
Tue, 10 Jun 2014 14:32:02 +0200
changeset 1 260cb5ec6c19
permissions -rw-r--r--
Update contrib.
     1 /*
     2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
     3 * All rights reserved.
     4 * This component and the accompanying materials are made available
     5 * under the terms of "Eclipse Public License v1.0"
     6 * which accompanies this distribution, and is available
     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
     8 *
     9 * Initial Contributors:
    10 * Nokia Corporation - initial contribution.
    11 *
    12 * Contributors:
    13 *
    14 * Description:       
    15 *
    16 */
    17 
    18 
    19 // [INCLUDE FILES] - do not remove
    20 #include <e32math.h>
    21 #include "widecharclassapiBCTest.h"
    22 
    23 #include <stl\_cwchar.h>
    24 #include <stdio.h>
    25 #include <time.h>
    26 #include <stdarg.h>
    27 
    28 
    29 // EXTERNAL DATA STRUCTURES
    30 //extern  ?external_data;
    31 
    32 // EXTERNAL FUNCTION PROTOTYPES  
    33 //extern ?external_function( ?arg_type,?arg_type );
    34 
    35 // CONSTANTS
    36 //const ?type ?constant_var = ?constant;
    37 
    38 // MACROS
    39 //#define ?macro ?macro_def
    40 
    41 // LOCAL CONSTANTS AND MACROS
    42 //const ?type ?constant_var = ?constant;
    43 //#define ?macro_name ?macro_def
    44 
    45 // MODULE DATA STRUCTURES
    46 //enum ?declaration
    47 //typedef ?declaration
    48 
    49 // LOCAL FUNCTION PROTOTYPES
    50 //?type ?function_name( ?arg_type, ?arg_type );
    51 
    52 // FORWARD DECLARATIONS
    53 //class ?FORWARD_CLASSNAME;
    54 
    55 // ============================= LOCAL FUNCTIONS ===============================
    56 
    57 // -----------------------------------------------------------------------------
    58 // ?function_name ?description.
    59 // ?description
    60 // Returns: ?value_1: ?description
    61 //          ?value_n: ?description_line1
    62 //                    ?description_line2
    63 // -----------------------------------------------------------------------------
    64 //
    65 /*
    66 ?type ?function_name(
    67     ?arg_type arg,  // ?description
    68     ?arg_type arg)  // ?description
    69     {
    70 
    71     ?code  // ?comment
    72 
    73     // ?comment
    74     ?code
    75     }
    76 */
    77 
    78 // ============================ MEMBER FUNCTIONS ===============================
    79 
    80 // -----------------------------------------------------------------------------
    81 // CwidecharclassapiBCTest::Case
    82 // Returns a test case by number.
    83 //
    84 // This function contains an array of all available test cases 
    85 // i.e pair of case name and test function. If case specified by parameter
    86 // aCaseNumber is found from array, then that item is returned.
    87 // 
    88 // The reason for this rather complicated function is to specify all the
    89 // test cases only in one place. It is not necessary to understand how
    90 // function pointers to class member functions works when adding new test
    91 // cases. See function body for instructions how to add new test case.
    92 // -----------------------------------------------------------------------------
    93 //
    94 const TCaseInfo CwidecharclassapiBCTest::Case ( 
    95     const TInt aCaseNumber ) const 
    96      {
    97 
    98     /**
    99     * To add new test cases, implement new test case function and add new 
   100     * line to KCases array specify the name of the case and the function 
   101     * doing the test case
   102     * In practice, do following
   103     * 1) Make copy of existing test case function and change its name
   104     *    and functionality. Note that the function must be added to 
   105     *    widecharclassapiBCTest.cpp file and to widecharclassapiBCTest.h 
   106     *    header file.
   107     *
   108     * 2) Add entry to following KCases array either by using:
   109     *
   110     * 2.1: FUNCENTRY or ENTRY macro
   111     * ENTRY macro takes two parameters: test case name and test case 
   112     * function name.
   113     *
   114     * FUNCENTRY macro takes only test case function name as a parameter and
   115     * uses that as a test case name and test case function name.
   116     *
   117     * Or
   118     *
   119     * 2.2: OOM_FUNCENTRY or OOM_ENTRY macro. Note that these macros are used
   120     * only with OOM (Out-Of-Memory) testing!
   121     *
   122     * OOM_ENTRY macro takes five parameters: test case name, test case 
   123     * function name, TBool which specifies is method supposed to be run using
   124     * OOM conditions, TInt value for first heap memory allocation failure and 
   125     * TInt value for last heap memory allocation failure.
   126     * 
   127     * OOM_FUNCENTRY macro takes test case function name as a parameter and uses
   128     * that as a test case name, TBool which specifies is method supposed to be
   129     * run using OOM conditions, TInt value for first heap memory allocation 
   130     * failure and TInt value for last heap memory allocation failure. 
   131     */ 
   132 
   133     static TCaseInfoInternal const KCases[] =
   134         {
   135         // [test cases entries] - do not remove
   136         
   137         // NOTE: When compiled to GCCE, there must be Classname::
   138         // declaration in front of the method name, e.g. 
   139         // CwidecharclassapiBCTest::PrintTest. Otherwise the compiler
   140         // gives errors.
   141         
   142         ENTRY( "Arithmetic Functions test", CwidecharclassapiBCTest::ArithmeticTest ),
   143         ENTRY( "File Manipulation test", CwidecharclassapiBCTest::FileManipulationTest ),
   144         ENTRY( "Console Operations test", CwidecharclassapiBCTest::ConsoleOperationsTest ),
   145         ENTRY( "String Operations test", CwidecharclassapiBCTest::StringOperationsTest ),
   146         ENTRY( "Conversion Operations test", CwidecharclassapiBCTest::ConversionOperationsTest ),
   147         // Example how to use OOM functionality
   148         //OOM_ENTRY( "Loop test with OOM", CwidecharclassapiBCTest::LoopTest, ETrue, 2, 3),
   149         //OOM_FUNCENTRY( CwidecharclassapiBCTest::PrintTest, ETrue, 1, 3 ),
   150         };
   151 
   152     // Verify that case number is valid
   153     if( (TUint) aCaseNumber >= sizeof( KCases ) / 
   154                                sizeof( TCaseInfoInternal ) )
   155         {
   156         // Invalid case, construct empty object
   157         TCaseInfo null( (const TText*) L"" );
   158         null.iMethod = NULL;
   159         null.iIsOOMTest = EFalse;
   160         null.iFirstMemoryAllocation = 0;
   161         null.iLastMemoryAllocation = 0;
   162         return null;
   163         } 
   164 
   165     // Construct TCaseInfo object and return it
   166     TCaseInfo tmp ( KCases[ aCaseNumber ].iCaseName );
   167     tmp.iMethod = KCases[ aCaseNumber ].iMethod;
   168     tmp.iIsOOMTest = KCases[ aCaseNumber ].iIsOOMTest;
   169     tmp.iFirstMemoryAllocation = KCases[ aCaseNumber ].iFirstMemoryAllocation;
   170     tmp.iLastMemoryAllocation = KCases[ aCaseNumber ].iLastMemoryAllocation;
   171     return tmp;
   172 
   173     }
   174 
   175 
   176 int WriteVarPrintfConsole (char *format, ...)
   177 {
   178   int result;
   179   va_list args;
   180   va_start (args, format);
   181   result = std::vwprintf (L"%d", args);
   182   va_end (args);
   183   return result;
   184 }
   185 
   186 int WriteVarPrintfFile (FILE * stream, char * format, ...)
   187 {
   188   int result;
   189   va_list args;
   190   va_start (args, format);
   191   result = std::vfwprintf (stream, L"%d", args);
   192   va_end (args);
   193   return result;
   194 }
   195 
   196 int WriteVarPrintfString (wchar_t * outputBuf, int sizeBuf, char * format, ...)
   197 {
   198   int result;
   199   va_list args;
   200   va_start (args, format);
   201   result = std::vswprintf (outputBuf, sizeBuf, L"%d", args);
   202   va_end (args);
   203   return result;
   204 }
   205 
   206 
   207 
   208 
   209 TInt CwidecharclassapiBCTest::FileManipulationTest( TTestResult& aResult )
   210     {
   211   		int testError = 0;
   212 __UHEAP_MARK;
   213 
   214   		
   215 		const  wchar_t *wsList = L"This is Wide Character Class API test.";
   216 		const  wchar_t *wPrintfTestFormat = L"%d";
   217 		
   218 		wchar_t wsListRead[64];
   219 		wchar_t wPrintfTestReadList[64];
   220 		std::wint_t wc = 88;
   221 		int c = 65;
   222 
   223 
   224 		char fileName[]="c:\\data\\others\\widechartest.txt";
   225 		remove(fileName);
   226 		
   227 		FILE *fp = NULL;
   228 		
   229 		/* opening the output file */
   230 		fp = fopen(fileName,"w");
   231 		if(fp == NULL)
   232 		{
   233 		   testError++;
   234 		}
   235 
   236 //Test std::fwide
   237 		int fileOrientation ;
   238 		
   239 		fileOrientation = std::fwide(fp, 0);
   240 
   241 
   242 //Test std::fwprintf
   243 		int fWritePrResult = std::fwprintf(fp, wPrintfTestFormat, c);
   244 		if(fWritePrResult < 0)
   245 			testError++;
   246 		
   247 //Test std::vfwprintf
   248 		int fWriteVPrResult = WriteVarPrintfFile(fp, "%d", c);
   249 		if(fWriteVPrResult < 0)
   250 			testError++;
   251 		
   252 		
   253 //Test std::fputwc		 
   254 		std::wint_t fWriteWCResult = std::fputwc(wc,fp);
   255 		if(fWriteWCResult == WEOF)
   256 			testError++;
   257 		
   258 //Test std::fputws		 
   259 		int fWriteWSResult = std::fputws(wsList, fp);
   260 		if(fWriteWSResult < 0)
   261 			testError++;
   262 		
   263 	
   264 		fclose(fp);
   265 		
   266 		
   267 		
   268 		int wsListLength = std::wcslen(wsList);
   269 		int wPrintTestListLength = std::wcslen(wPrintfTestFormat);
   270 		
   271 
   272 		/* opening the input file */
   273 		fp = fopen(fileName,"r");
   274 		if(fp == NULL)
   275 		{
   276 		   testError++;
   277 		}
   278 
   279 //Test std::fwscanf
   280 		int inpC;
   281 		int fReadPrResult = std::fwscanf(fp, wPrintfTestFormat, &inpC);
   282 		if(fReadPrResult < 0)
   283 			testError++;
   284 		fReadPrResult = std::fwscanf(fp, wPrintfTestFormat, &inpC);
   285 		if(fReadPrResult < 0)
   286 			testError++;
   287 
   288 		
   289 //Test std::fputwc		 
   290 		std::wint_t fReadWCResult = std::fgetwc(fp);
   291 		if(fReadWCResult == WEOF)
   292 			testError++;
   293 		
   294 //Test std::fgetws		 
   295 		wchar_t * ptrReadWSResult = std::fgetws(wsListRead, wsListLength, fp);
   296 		if(ptrReadWSResult == 0)
   297 			testError++;
   298 		
   299 		
   300 		fclose(fp);
   301 		remove(fileName);
   302   		
   303   		
   304     // Test case passed
   305 __UHEAP_MARKEND;
   306     // Sets test case result and description(Maximum size is KStifMaxResultDes)
   307 	if(testError)
   308 	{
   309  	   _LIT( KDescriptionErr, "FileManipulationTest failed" );
   310  	   aResult.SetResult( KErrGeneral, KDescriptionErr );
   311 
   312  	   // Case was executed
   313 	    return testError;
   314 		
   315 	}
   316 	
   317 
   318     // Case was executed
   319     return KErrNone;
   320 
   321     }
   322     
   323     
   324 TInt CwidecharclassapiBCTest::ConsoleOperationsTest( TTestResult& aResult )
   325     {
   326   		int testError = 0;
   327 __UHEAP_MARK;
   328   		
   329   		freopen("c:\\data\\others\\myconsole.txt", "w", stdout);
   330 //Test std::putwc 		
   331   		wchar_t * consoleMessage = L"Enter Character 'v' ";
   332 		fputws(consoleMessage, stdout);
   333 		wint_t putWCResult = std::putwc(L':', stdout);
   334 
   335 //Test std::vwprintf
   336 		int c=89;
   337 		int fWriteVPrResult = WriteVarPrintfConsole("%d", c);
   338 		if(fWriteVPrResult < 0)
   339 			testError++;
   340 
   341 		ungetwc(L'v', stdin);
   342 
   343 //Test std::getwc		
   344 		wint_t getWCResult;
   345 		getWCResult = std::getwc(stdin);
   346 
   347 
   348 		ungetwc(L'v', stdin);
   349 		getWCResult = std::getwchar();
   350 
   351 		fclose(stdout);
   352 		fclose(stderr);
   353 		fclose(stdin);
   354 
   355  		
   356     // Test case passed
   357 __UHEAP_MARKEND;
   358     // Sets test case result and description(Maximum size is KStifMaxResultDes)
   359 	if(testError)
   360 	{
   361  	   // Case was executed
   362 	    return testError;
   363 		
   364 	}
   365 	
   366 
   367     // Case was executed
   368     return KErrNone;
   369 
   370 
   371     }
   372     
   373     
   374 TInt CwidecharclassapiBCTest::StringOperationsTest( TTestResult& aResult )
   375     {
   376   		int testError = 0;
   377 __UHEAP_MARK;
   378   		
   379 //Test std::wcscat  		
   380 		wchar_t wcSRC[64] = L"Wide character";
   381 		wchar_t wcDST[64] = L"Class API";
   382 		wchar_t *wcWCSCATResult= std::wcscat(wcDST, (const wchar_t*)wcSRC);
   383 
   384 //Test std::wcsncat		
   385 		wchar_t *wcWCSNCATResult= std::wcsncat(wcDST, (const wchar_t*)wcSRC, 4);
   386 
   387 		
   388 		wchar_t *wcSTR = L"Wide Character Class API";
   389 		wchar_t wcSearch = L'A';
   390 //Test std::wcschr
   391 		wchar_t* wcWCSCHRResult = std::wcschr(wcSTR, wcSearch);
   392 
   393 //Test std::wcsrchr
   394 		wchar_t* wcWCSRCHRResult = std::wcsrchr(wcSTR, wcSearch);
   395 
   396 //Test std::wmemchr
   397 		wchar_t* wcWMEMCHRResult = std::wmemchr(wcSTR, wcSearch, 4);
   398 
   399 
   400 //Test std::wcscmp
   401 		wchar_t *wcS1 = L"ABCDE";
   402 		wchar_t *wcS2 = L"ACCD";
   403 		int intWCSCMPResult = std::wcscmp(wcS1, wcS2);
   404 
   405 //Test std::wcsncmp
   406 		int intWCSNCMPResult = std::wcsncmp(wcS1, wcS2, 4);
   407 
   408 //Test std::wcscoll
   409 		int intWCSCOLLResult = std::wcscoll(wcS1, wcS2);
   410 
   411 //Test std::wmemcmp
   412 		int intWMEMCMPResult = std::wmemcmp(wcS1, wcS2, 4);
   413 
   414 
   415 //Test std::wcscpy
   416 		wchar_t wcSRC1[64] = L"Wide character";
   417 		wchar_t wcDST1[64] = L"Class API";
   418 		wchar_t *wcWCSCPYResult = std::wcscpy(wcDST1, wcSRC1);
   419 
   420 //Test std::wcsncpy
   421 		wchar_t *wcWCSNCPYResult = std::wcsncpy(wcDST1, wcSRC1, 4);
   422 
   423 //Test std::wmemcpy
   424 		wchar_t *wcWMEMCPYResult = std::wmemcpy(wcDST1, wcSRC1, 4);
   425 
   426 //Test std::wmemmove
   427 		wchar_t *wcWMEMMOVEResult = std::wmemmove(wcDST1, wcSRC1, 4);
   428 
   429 //Test std::wmemset
   430 		wchar_t *wcWMEMSETResult = std::wmemset(wcDST1, L'V', 4);
   431 
   432 //Test std::wcsxfrm
   433 		size_t lenWCSXFRMResult = std::wcsxfrm(wcDST1, wcSRC1, 15);
   434 
   435 //Test std::wcscspn
   436  		const wchar_t wcSTR1[30] = L"1234567890ABCDE!@#$$";
   437   		const wchar_t wcSpanset[20] = L"ABCDE!@#$$";
   438 		size_t intWCSCSPNResult = std::wcscspn(wcSTR1, wcSpanset);
   439 	
   440 //Test std::wcsspn	
   441 		size_t intWCSSPNResult = std::wcsspn(wcSTR1, wcSpanset);
   442 
   443 //Test std::wcspbrk	
   444 		wchar_t * wcptrWCSSPNResult = std::wcspbrk(wcSTR1, wcSpanset);
   445 	
   446 	
   447 //Test std::wcsftime	
   448 		time_t rawtime;
   449   		struct tm * timeinfo;
   450   		wchar_t wcTimeOutput [80];
   451   		time ( &rawtime );
   452   		timeinfo = localtime ( &rawtime );
   453   		size_t lenString = std::wcsftime (wcTimeOutput,80,L"Now is %I:%M%p.",timeinfo);
   454 	
   455 //Test std::wcslen	
   456 		size_t lenSTR = std::wcslen(wcSTR);
   457 		
   458 //Test std::wcsstr	
   459 		wchar_t wcSTR2[64] = L"Wide character Class API";
   460 		wchar_t wcSUBSTR[64] = L"Class API";
   461 		wchar_t* wcptrWCSSTR = std::wcsstr(wcSTR2, wcSUBSTR);
   462 
   463 
   464 		wchar_t wcSTRDest[64];
   465 //Test std::swprintf	
   466 		wchar_t *formatSTR = L"%d";
   467 		int intSampleOutput = 78;
   468 		int returnPrintf = std::swprintf(wcSTRDest, 63, formatSTR, intSampleOutput);
   469 		
   470 //Test std::swscanf	
   471 		int intSampleInput;
   472 		int returnScanf = std::swscanf(wcSTRDest, formatSTR, &intSampleInput);
   473   		
   474   		
   475 //Test std::vswprintf
   476 		wchar_t outputSTR[32];
   477 		int c = 76;
   478 		int fWriteVPrResult = WriteVarPrintfString(outputSTR, 32, "%d", c);
   479 		if(fWriteVPrResult < 0)
   480 			testError++;
   481  		
   482   		
   483     // Test case passed
   484 __UHEAP_MARKEND;
   485     // Sets test case result and description(Maximum size is KStifMaxResultDes)
   486 	if(testError)
   487 	{
   488  	   // Case was executed
   489 	    return testError;
   490 		
   491 	}
   492 	
   493     // Case was executed
   494     return KErrNone;
   495 
   496 
   497     }
   498     
   499     
   500 TInt CwidecharclassapiBCTest::ConversionOperationsTest( TTestResult& aResult )
   501     {
   502   		int testError = 0;
   503 //__UHEAP_MARK;
   504 
   505  		size_t len;
   506 		char *szMBTest = "this is test";
   507 		mbstate_t mbs;
   508 		mbstate_t ps;
   509  		
   510 //Test std::btowc
   511 		int c = 65;
   512 		std::wint_t wc;
   513  		/* converting single byte to wide-character */
   514  		wc = std::btowc(c);
   515   		
   516 
   517 //Test std::wcstod
   518 		 wchar_t wcs1[21] = L"  1.23abcd";
   519 		 wchar_t wcs2[5]=L"abcd";
   520 		 wchar_t *eptr;
   521 		 float d;
   522 		 /* convert wide-char string to double */  
   523 		 d = std::wcstod(wcs1, &eptr);
   524 		 /* compare the result */
   525 		 if(!((d == 1.23F) && !(std::wcscmp (eptr, wcs2))))
   526 		   testError++;
   527   
   528 
   529 //Test std::wcstol
   530 		 wchar_t wcs3[8]=L".23abcd";
   531 		 long longintOutput;
   532 		 /* convert wide-char string to long int */  
   533 		 longintOutput = std::wcstol(wcs1, &eptr, 10);
   534 		 /* compare the result */
   535 		 if(!((longintOutput == 1) && !(std::wcscmp (eptr, wcs3))))
   536 		   testError++;
   537   
   538 //Test std::wcstoul
   539 		 unsigned long unslongintOutput;
   540 		 /* convert wide-char string to long int */  
   541 		 unslongintOutput = std::wcstoul(wcs1, &eptr, 10);
   542 		 /* compare the result */
   543 		 if(!((unslongintOutput == 1) && !(std::wcscmp (eptr, wcs3))))
   544 		   testError++;
   545   
   546 
   547 
   548 //Test std::wcstok
   549 		 const wchar_t *seps = L":";
   550 		 wchar_t *last, *tok, text[] = L"one:twothree";
   551 		              
   552 		 tok = std::wcstok(text, seps, &last);
   553 		 if(!tok)
   554 		   testError++;
   555 		 
   556 		 
   557 //Test std::mbsrtowcs
   558 		wchar_t wideCharStringOutput[64];
   559 		len = std::mbsrtowcs(wideCharStringOutput, (const char**)&szMBTest, 10, &ps);
   560 		/* checking for error */
   561 		if(len < 0)
   562 		{
   563 			testError++;
   564 		}
   565 	
   566 //Test std::wcsrtombs
   567 		char mbOutputString[64];
   568 		wchar_t *wcptrString = wideCharStringOutput;
   569 		size_t lenWCS = std::wcsrtombs(mbOutputString, (const wchar_t**) &wcptrString, len, &ps);
   570 
   571 
   572 //Test std::wcrtomb
   573 		wchar_t wcWCRTOMB = L'v';
   574 		char mbWCRTOMB[10];
   575 		len = std::wcrtomb(mbWCRTOMB, wcWCRTOMB, &ps);
   576 
   577     // Test case passed
   578 __UHEAP_MARKEND ;
   579 
   580 
   581     // Sets test case result and description(Maximum size is KStifMaxResultDes)
   582 	if(testError)
   583 	{
   584 	    return testError;
   585 		
   586 	}
   587 	
   588 
   589 
   590     // Case was executed
   591     return KErrNone;
   592 
   593 
   594     }
   595 
   596 
   597 
   598 TInt CwidecharclassapiBCTest::ArithmeticTest( TTestResult& aResult )
   599     {
   600 
   601   		int testError = 0;
   602 __UHEAP_MARK;
   603 		
   604 
   605 //Test std::mbrlen
   606 		char *szMBTest = "this is test";
   607 		int aa = 2;
   608 		mbstate_t mbs;
   609 		memset(&mbs, 0, sizeof(mbs));
   610 //		size_t charlen = std::mbrlen(szMBTest, 6, &mbs); 
   611 		size_t charlen = std::mbrlen((const char*)&aa, 6, &mbs); 
   612 
   613 //Test std::mbrtowc
   614 		size_t len;
   615 		wchar_t wcMBCOutput[100];
   616 		char *s = "a";
   617 		size_t n = 1;
   618 		mbstate_t ps;
   619 		/* converting multibyte sequence to a wide-char sequence */
   620 		len = std::mbrtowc(wcMBCOutput,(const char *) s, n, &ps);
   621 		/* checking for error value */
   622 		if(len < 0)
   623 		{
   624 			testError++;
   625 		}
   626 
   627 
   628 //Test std::mbsinit
   629 		int mbINITOutput = std::mbsinit((const mbstate_t*) &ps);
   630 
   631 
   632     // Test case passed
   633 
   634     // Sets test case result and description(Maximum size is KStifMaxResultDes)
   635 	if(testError)
   636 	{
   637  	   _LIT( KDescriptionErr, "ArithmeticTest failed" );
   638  	   aResult.SetResult( KErrGeneral, KDescriptionErr );
   639 
   640  	   // Case was executed
   641 	    return testError;
   642 		
   643 	}
   644 	
   645     _LIT( KDescription, "LoopTest passed" );
   646     aResult.SetResult( KErrNone, KDescription );
   647 
   648 __UHEAP_MARK;
   649 
   650 // Case was executed
   651     return KErrNone;
   652 
   653     }
   654 
   655 
   656 
   657 // -----------------------------------------------------------------------------
   658 // ?classname::?member_function
   659 // ?implementation_description
   660 // (other items were commented in a header).
   661 // -----------------------------------------------------------------------------
   662 //
   663 /*
   664 ?type ?classname::?member_function(
   665    ?arg_type arg,
   666    ?arg_type arg )
   667    {
   668 
   669    ?code
   670 
   671    }
   672 */
   673 
   674 // ========================== OTHER EXPORTED FUNCTIONS =========================
   675 
   676 // -----------------------------------------------------------------------------
   677 // ?function_name implements...
   678 // ?implementation_description.
   679 // Returns: ?value_1: ?description
   680 //          ?value_n: ?description
   681 //                    ?description
   682 // -----------------------------------------------------------------------------
   683 //
   684 /*
   685 ?type  ?function_name(
   686     ?arg_type arg,  // ?description
   687     ?arg_type arg )  // ?description
   688     {
   689 
   690     ?code
   691 
   692     }
   693 */
   694 //  [End of File] - do not remove