[Cosm Logo]

Input/Output and String Functions

v3Input

Syntax

 
#include "cosmio.h"
u64 v3Input( u8 * buffer, u64 length, u32 echo );

Description

Read length bytes from stdin into the buffer. If echo is V3_IO_NOECHO then the typed characters will not be echoed in any way (for password entry etc), otherwise echo should be V3_IO_ECHO. The buffer will not be terminated with a 0, becasue it is not a string. Usually used with a length of 1.

Return Values

Number of bytes read, 0xFFFFFFFFFFFFFFFF (-1) indicates EOF.

Errors

None.

Example

 
  u8 * buffer;
  u64 size;
  u64 len;
  u64 eof;

  /* ... */

  _V3_SET64( size, 00000000, 00000001 );
  _V3_SET64( eof, FFFFFFFF, FFFFFFFF );

  v3PrintA( "Hit a key: " );
  len = v3Input( buffer, size, V3_IO_ECHO );

  if ( ( v3u64Eq( len, eof ) ) || ( !v3u64Eq( len, size ) ) )
  {
    /* EOF reached */
  }

v3InputA

Syntax

 
#include "cosmio.h"
u64 v3InputA( ascii * buffer, u64 max_chars, u32 echo );

Description

Reads up to max_chars-1 ascii characters from standard input device until EOF or '\n' is reached. buffer will always be a terminated string if input is read. If echo is V3_IO_NOECHO then the typed characters will not be echoed in any way (for password entry etc), otherwise echo should be V3_IO_ECHO. Any input beyond max_chars-1 will be discarded, so use a large enough buffer.

Return Values

Number of characters input, 0xFFFFFFFFFFFFFFFF (-1) indicates EOF.

Errors

None.

Example

 
  ascii * buffer;
  u64 size;
  u64 len;
  u64 eof_length;

  /* ... */

  _V3_SET64( size, 00000000, 000000FF );

  len = v3InputA( buffer, size, V3_IO_ECHO );

  _V3_SET64( eof_length, FFFFFFFF, FFFFFFFF );

  if ( v3u64Eq( len, eof_length ) )
  {
    /* EOF */
  }

This will read up to size-1 characters into buffer from standard input.

v3InputU

Syntax

 
#include "cosmio.h"
u64 v3InputU( unicode * buffer, u64 max_chars, u32 echo );

Description

Reads up to max_chars-1 unicode characters from standard input device until EOF or '\n' is reached. buffer will always be a terminated string if input is read. If echo is V3_IO_NOECHO then the typed characters will not be echoed in any way (for password entry etc), otherwise echo should be V3_IO_ECHO.

Return Values

Number of characters input, 0xFFFFFFFFFFFFFFFF (-1) indicates EOF.

Errors

None.

Example

 
  unicode * buffer;
  u64 size;
  u64 len;
  u64 eof_length;

  /* ... */

  _V3_SET64( size, 00000000, 000000FF );

  len = v3InputU( buffer, size, V3_IO_ECHO );

  _V3_SET64( eof_length, FFFFFFFF, FFFFFFFF );

  if ( v3u64Eq( len, eof_length ) )
  {
    /* EOF */
  }

This will read up to size-1 characters into buffer from standard input.

v3StrLengthA

Syntax

 
#include "cosmio.h"
u64 v3StrLengthA( const ascii * string );

Description

Get the length of the ascii string pointed to by string.

Return Values

The length of the ascii string in characters.

Errors

None.

Example

 
  ascii * string;
  u64 size;
  u64 length;

  _V3_SET64( size, 00000000, 00000400 );

  string = v3MemAlloc( size, (u32) 0 );
  string = (ascii *) "A 27 character test string.";

  length = v3StrLengthA( string );

v3StrLengthU

Syntax

 
#include "cosmio.h"
u64 v3StrLengthU( const unicode * string );

Description

Get the length of the unicode string pointed to by string.

Return Values

The length of the unicode string in characters.

Errors

None.

Example

 
  unicode string[256];
  u64 size;
  u64 length;

  _V3_SET64( size, 00000000, 00000100 );

  if ( v3StrCopyUA( string,
    (ascii *) "A 27 character test string.", size ) != V3_PASS )
  {
    /* Error */
  }

  length = v3StrLengthU( string );

v3StrCopyA

Syntax

 
#include "cosmio.h"
s32 v3StrCopyA( ascii * dest, const ascii * src, u64 max_chars );

Description

Copy a string of up to max_chars-1 ascii characters from src to dest, including the terminating '\0'. If the src string is longer then max_chars-1 the function will fail and do nothing.

Return Values

V3_PASS on success, or V3_FAIL on failure.

Errors

Possible causes of an failure:

  • A parameter was NULL or 0.
  • The src string was longer then max_chars-1.

Example

 
  ascii string[256];
  ascii copy[256];
  u64 size;

  /* ... */

  if ( v3StrCopyA( copy, string, size ) != V3_PASS )
  {
    /* Error */
  }

v3StrCopyU

Syntax

 
#include "cosmio.h"
s32 v3StrCopyU( unicode * dest, const unicode * src, u64 max_chars );

Description

Copy a string of up to max_cahrs-1 unicode characters from src to dest, including the terminating '\0'. If the src string is longer then max_chars-1 the function will fail and do nothing.

Return Values

V3_PASS on success, or V3_FAIL on failure.

Errors

Possible causes of an failure:

  • A parameter was NULL or 0.
  • The src string was longer then max_chars-1.

Example

 
  unicode string[256];
  unicode copy[256];
  u64 size;

  /* ... */

  if ( v3StrCopyU( copy, string, size ) != V3_PASS )
  {
    /* Error */
  }

v3StrCopyUA

Syntax

 
#include "cosmio.h"
s32 v3StrCopyUA( unicode * dest, const ascii * src, u64 max_chars );

Description

Converts the ascii string to unicode using the trivial mapping, up to and including the terminating '\0'. Only strings up to max_chars-1 characters long will be converted.

Return Values

V3_PASS on success, or V3_FAIL on failure.

Errors

Possible causes of an failure:

  • A parameter was NULL or 0.
  • The src string was longer then max_chars-1.

Example

 
  unicode buffer[256];
  u64 size;

  _V3_SET64( size, 00000000, 00000100 );

  /* ... */

  if ( v3StrCopyUA( buffer, (ascii *) "Test string", size )
     != V3_PASS )
  {
    /* Error */
  }

v3StrAppendA

Syntax

 
#include "cosmio.h"
s32 v3StrAppendA( ascii * stringA, const ascii * stringB, u64 max_chars );

Description

Appends the ascii stringB to the end of stringA, only if the sum of the string lengths is less than max_chars-1.

Return Values

V3_PASS on success, or V3_FAIL on failure.

Errors

Possible causes of an failure:

  • A parameter was NULL or 0.
  • Size of the resulting string would be longer than max_chars-1

Example

 
  ascii buffer[256];
  u64 size;

  _V3_SET64( size, 00000000, 00000100 );

  /* ... */

  if ( v3StrAppendA( buffer, (ascii *) "Test string", size )
     != V3_PASS )
  {
    /* Error */
  }

v3StrAppendU

Syntax

 
#include "cosmio.h"
s32 v3StrAppendU( unicode * stringA, const unicode * stringB, u64 max_chars );

Description

Appends the unicode stringB to the end of stringA, only if the sum of the string lengths is less than max_chars-1

Return Values

V3_PASS on success, or V3_FAIL on failure.

Errors

Possible causes of an failure:

  • A parameter was NULL or 0.
  • Size of the resulting string would be longer than max_chars-1

Example

 
  unicode buffer[256];
  unicode buffer1[256];
  u64 size;

  _V3_SET64( size, 00000000, 00000100 );

  /* ... */

  if ( v3StrCopyUA( buffer1, (ascii *) "Test string", size )
     != V3_PASS )
  {
    /* Error */
  }

  if ( v3StrAppendU( buffer, buffer1, size )
     != V3_PASS )
  {
    /* Error */
  }

v3StrCmpA

Syntax

 
#include "cosmio.h"
s32 v3StrCmpA( const ascii * stringA, const ascii * stringB,
  u64 max_chars );

Description

Compare the two ascii strings, up to max_chars or the end of one string.

Return Values

0 if the strings are identical, a postive number if the ascii code of the first different character in stringA is greater than the ascii code of that character in stringB, or a negative number if the ascii code of the first different character in stringA is less than the ascii code of that character in stringB. If any parameter is NULL/0 then it returns -1 unless stringA == stringB.

Errors

None.

Example

 
  ascii stringa[128];
  ascii stringb[128];
  u64 max;

  /* set stringa and stringb to something */

  if ( v3StrCmpA( stringa, stringb, max ) != 0 )
  {
    /* Strings do not match */
  }

v3StrCmpU

Syntax

 
#include "cosmio.h"
s32 v3StrCmpU( const unicode * stringA, const unicode * stringB,
  u64 max_chars );

Description

Compare the two unicode strings, up to max_chars or the end of one string.

Return Values

0 if the strings are identical, a postive number if the ascii code of the first different character in stringA is greater than the ascii code of that character in stringB, or a negative number if the ascii code of the first different character in stringA is less than the ascii code of that character in stringB. If any parameter is NULL/0 then it returns -1 unless stringA == stringB.

Errors

None.

Example

 
  unicode stringa[128];
  unicode stringb[128];
  u64 max;

  /* set stringa and stringb to something */

  if ( v3StrCmpU( stringa, stringb, max ) != 0 )
  {
    /* Strings do not match */
  }

v3StrCharA

Syntax

 
#include "cosmio.h"
ascii * v3StrCharA( const ascii * string, ascii match_char,
  u64 max_chars );

Description

Locate match_char in the string, which is up to max_chars long.

Return Values

A pointer to the first ascii character matching match_char in the string, or NULL if it does not occur in the string.

Errors

None.

Example

 
  ascii stringa[128];
  ascii * found;
  u64 max;

  /* read in string */

  if ( ( found = v3StrCharA( stringa, 'a', max ) ) != NULL )
  {
    /* the character 'a' was found in the string */
  }

v3StrCharU

Syntax

 
#include "cosmio.h"
unicode * v3StrCharU( const unicode * string, unicode match_char,
  u64 max_chars );

Description

Locate match_char in the string, which is up to max_chars long.

Return Values

A pointer to the first unicode character matching match_char in the string, or NULL if it does not occur in the string.

Errors

None.

Example

 
  unicode stringa[128];
  unicode * found;
  u64 max;

  /* read in string */

  if ( ( found = v3StrCharU( stringa, (unicode) 'a', max ) ) != NULL )
  {
    /* the character 'a' was found in the string */
  }

v3StrStrA

Syntax

 
#include "cosmio.h"
ascii * v3StrStrA( const ascii * string, const ascii * substring,
  u64 max_chars );

Description

Locate substring in the string, which is up to max_chars-1 long.

Return Values

A pointer to the first match of substring in string, or NULL if it does not occur in the string.

Errors

None.

Example

 



    


    
    

      v3StrStrU
    


    
Syntax



#include "cosmio.h"
unicode * v3StrStrU( const unicode * string, const unicode * substring,
  u64 max_chars );




    
Description

    

      Locate substring in the string, which is up to
      max_chars-1 long.
    


    
Return Values

    

      A pointer to the first match of substring in string,
      or NULL if it does not occur in the string.
    


    
Errors

    

      None.
    


    
Example






    


    
    

      v3{integral type}A
    


    
Syntax



#include "cosmio.h"
s32 v3u32A( u32 * result, ascii ** end, const ascii * string,
  u32 radix );
s32 v3s32A( s32 * result, ascii ** end, const ascii * string,
  u32 radix );
s32 v3u64A( u64 * result, ascii ** end, const ascii * string,
  u32 radix );
s32 v3s64A( s64 * result, ascii ** end, const ascii * string,
  u32 radix );
s32 v3u128A( u128 * result, ascii ** end, const ascii * string,
  u32 radix );
s32 v3s128A( s128 * result, ascii ** end, const ascii * string,
  u32 radix );




    
Description

    

      Convert the ascii string written in radix to the
      number type. Numbers are of the form: [space*][+|-][0|0x|0X]{0-9a-zA-Z}+
      radix must be 2-36 or 0. If radix is 0, numbers
      starting with "0x" or "0X" will be read as base 16, numbers starting
      with 0 will be interpreted as base 8, and all others will be base 10.
      If end is not NULL, it will be set to the character after the
      last character used in the number. For u8 and u16 types use the u32
      function and typecast the result. Note that use of radixes
      other then 2, 8, 10, or 16 are generally useless.
    


    
Return Values

    

      Sets result to the number and returns V3_PASS on success, or
      sets result to 0 and returns V3_FAIL on failure.
    


    
Errors

    

      None.
    


    
Example






    


    
    

      v3{integral type}U
    


    
Syntax



#include "cosmio.h"
s32 v3u32U( u32 * result, unicode ** end, const unicode * string,
  u32 radix );
s32 v3s32U( s32 * result, unicode ** end, const unicode * string,
  u32 radix );
s32 v3u64U( u64 * result, unicode ** end, const unicode * string,
  u32 radix );
s32 v3s64U( s64 * result, unicode ** end, const unicode * string,
  u32 radix );
s32 v3u128U( u128 * result, unicode ** end, const unicode * string,
  u32 radix );
s32 v3s128U( s128 * result, unicode ** end, const unicode * string,
  u32 radix );




    
Description

    

      Convert the unicode string written in radix to the
      number type. Numbers are of the form: [space*][+|-][0|0x|0X]{0-9a-zA-Z}+
      Numbers may be in any language form supported by unicode.
      radix must be 2-36 or 0. If radix is 0, numbers
      starting with "0x" or "0X" will be read as base 16, numbers starting
      with 0 will be interpreted as base 8, and all others will be base 10.
      If end is not NULL, it will be set to the character after the
      last character used in the number. For u8 and u16 types use the u32
      function and typecast the result. Note that use of radixes
      other then 2, 8, 10, or 16 are generally useless.
    


    
Return Values

    

      Sets result to the number and returns V3_PASS on success, or
      sets result to 0 and returns V3_FAIL on failure.
    


    
Errors

    

      None.
    


    
Example






    


    
    

      v3{float type}A
    


    
Syntax



#include "cosmio.h"
s32 v3f32A( f32 * result, ascii ** end, const ascii * string );
s32 v3f64A( f64 * result, ascii ** end, const ascii * string );




    
Description

    

      Convert the ascii base-10 string to a floating point number.
      Numbers are of the form:
      [space*][+|-]{{0-9}+[.{0-9}*]|.{0-9}+}[{e|E}[+|-]{0-9}+]
      If end is not NULL, it will be set to the character after the
      last character used in the number.
    


    
Return Values

    

      Sets result to the number and returns V3_PASS on success, or
      sets result to +/- HUGE_VAL if the number was too large or 0
      if the string wasn't a number and returns V3_FAIL on failure.
    


    
Errors

    

      None.
    


    
Example






    


    
    

      v3{float type}U
    


    
Syntax



#include "cosmio.h"
s32 v3f32U( f32 * result, unicode ** end, const unicode * string );
s32 v3f64U( f64 * result, unicode ** end, const unicode * string );




    
Description

    

      Convert the unicode base-10 string to a floating point number.
      Numbers are of the form:
      [space*][+|-]{{0-9}+[.{0-9}*]|.{0-9}+}[{e|E}[+|-]{0-9}+]
      Digits can be the base-10 digits of any language that unicode supports.
      If end is not NULL, it will be set to the character after the
      last character used in the number.
    


    
Return Values

    

      Sets result to the number and returns V3_PASS on success, or
      sets result to +/- HUGE_VAL if the number was too large or 0
      if the string wasn't a number and returns V3_FAIL on failure.
    


    
Errors

    

      None.
    


    
Example






    


    
    

      v3PrintA
    


    
Syntax



#include "cosmio.h"
u64 v3PrintA( const ascii * format, ... );




    
Description

    

      Prints the formatted ascii text to the standard output device.
      All output buffers will be flushed before return.
    

    

      %[width][.prec]type_char
    

    

      [width]
      
    
        
  • 0n = min n characters are printed, pad 0
        
  • -n = min n characters are printed, left justify
        
  • n = min n characters are printed, no effect on type n|N
        
  • * = next argument (u32) will specify width
      


      [.prec]
      
    
        
  • .n = max n decimals places are printed for type f|F. Should
          always be set, default = 6.
        
  • .n = max n characters printed for type s|b. Default = 0.
        
  • .n = no effect on all other types
        
  • .* = next argument (u32) will specify precision
      

      [type_char]
      
    
        
  • c = single character
        
  • s = zero terminated string (ascii in "A" versions,
          unicode in "U" versions)
        
  • b = raw byte buffer, precision flag is length in bytes
        
  • f = f32 or f64, [-]dddd.dddddd
        
  • F = f32 or f64, [-]d.dddddd[Edd]
        
  • u = u32 dec
        
  • v = u64 dec
        
  • w = u128 dec
        
  • i = s32 dec
        
  • j = s64 dec
        
  • k = s128 dec
        
  • X = u32 hex (hex = [0-9A-F], always uppercase, no automatic
          "0x" prefix)
        
  • Y = u64 hex
        
  • Z = u128 hex
        
  • p = pointer, zero-padded hex - native length 32-bit|64-bit
        
  • n = bignum - (v3_BN *) dec
        
  • N = bignum - (v3_BN *) hex
      

      Note the mnemonics for the 32-bit (root) variants: c = character,
      s = string, f = float, b = buffer, u = unsigned, i = integer, X = hex,
      p = pointer, n = bignum.
    


    
Return Values

    

      Number of characters output.
    


    
Errors

    

      None.
    


    
Example



  ascii * output;
  void * foo;
  u64 size;

  _V3_SET64( size, 00000000, 000000FF );

  output = v3MemAlloc( size, (u32) V3_MEM_NORMAL );

  /* ... */

  v3PrintA( (ascii *) "Error: %.*s\n", v3u32u64( size ), output );
  v3PrintA( (ascii *) "Size: %04v bytes\n", size );
  v3PrintA( (ascii *) "foo points to: %p\nAddress of size is: %p\n",
            foo, &size );



    

      This would print something similar to (on a 32-bit machine):
    



  Error: Timeout -- try again later
  Size: 0255 bytes
  foo points to: 08049860
  Address of size is: 7FFFF7A8




    


    
    

      v3PrintU
    


    
Syntax



#include "cosmio.h"
u64 v3PrintU( const unicode * format, ... );




    
Description

    

      Prints the formatted unicode text to the standard output device.
      All output buffers will be flushed before return.
      See v3PrintA for format usage.
    


    
Return Values

    

      Number of characters output.
    


    
Errors

    

      None.
    


    
Example



  unicode string[256];
  unicode * output;
  void * foo;
  u64 size;

  _V3_SET64( size, 00000000, 00000100 );

  output = v3MemAlloc( v3u64Lsh( size, 1 ), (u32) V3_MEM_NORMAL );

  /* ... */

  if ( v3StrCopyUA( string, (ascii *) "Error: %.*s\n", size )
     != V3_PASS )
  {
    /* Error */
  }

  v3PrintU( string, v3u32u64( size ), output );

  if ( v3StCopyUA( string,
    (ascii *) "Size: %04v bytes\n", size ) != V3_PASS )
  {
    /* Error */
  }

  v3PrintU( string, size );

  if ( v3StrCopyUA( string, (ascii *)
    "foo points to: %p\nAddress of size is: %p\n", size ) != V3_PASS )
  {
    /* Error */
  }

  v3PrintU( string, foo, &size );



    

      This would print something similar to (on a 32-bit machine):
    



  Error: Timeout -- try again later
  Size: 0255 bytes
  foo points to: 08049860
  Address of size is: 7FFFF7A8




    


    
    

      v3PrintAStr
    


    
Syntax



#include "cosmio.h"
u64 v3PrintAStr( ascii * string, u64 max_chars,
  const ascii * format, ... );




    
Description

    

      Prints the formatted ascii text to the string. No more than
      max_chars-1 characters will be written to the string. See
      v3PrintA for format usage.
    


    
Return Values

    

      Number of characters written to string, or -1 if truncated due to
      max_chars.
    


    
Errors

    

      None.
    


    
Example



  ascii * output;
  void * foo;
  u64 size;
  u64 chars_output;

  _V3_SET64( size, 00000000, 000000FF );

  output = v3MemAlloc( size, (u32) V3_MEM_NORMAL );

  /* ... */

  chars_output = v3PrintAStr( output, size,
      (ascii *) "foo points to: %p\nAddress of size is: %p\n",
      foo, &size );

  if ( !v3u64Eq( chars_output, v3u64u32( 0 ) )
  {
    /* Error */
  }




    


    
    

      v3PrintUStr
    


    
Syntax



#include "cosmio.h"
u64 v3PrintUStr( unicode * string, u64 max_chars,
  const unicode * format, ... );




    
Description

    

      Prints the formatted unicode text to the string. No more the
      max_chars-1 characters will be written to the string. See
      v3PrintA for format usage.
    


    
Return Values

    

      Number of characters written to string, or -1 if truncated due to
      max_chars.
    


    
Errors

    

      None.
    


    
Example



  unicode string[256];
  unicode * output;
  void * foo;
  u64 size;
  u64 chars_output;

  _V3_SET64( size, 00000000, 00000100 );

  output = v3MemAlloc( v3u64Lsh( size, 1 ), (u32) V3_MEM_NORMAL );

  /* ... */

  if ( v3StrCopyUA( string, (ascii *)
    "foo points to: %p\nAddress of size is: %p\n", size ) != V3_PASS )
  {
    /* Error */
  }

  chars_output = v3PrintUStr( output, size, string, foo, &size );

  if ( v3u64Eq( chars_output, v3u64u32( 0 ) )
  {
    /* Error */
  }




    


    
    

      v3PrintAFile
    


    
Syntax



#include "cosmio.h"
u64 v3PrintAFile( v3_FILE * file, const ascii * format, ... );




    
Description

    

      Prints the formatted ascii text to the file. See
      v3PrintA for format usage.
    


    
Return Values

    

      Number of characters written to file.
    


    
Errors

    

      None.
    


    
Example



  ascii * output;
  u64 chars_written;
  u64 size;
  v3_FILE * file;

  _V3_SET64( size, 00000000, 000000FF );

  /* ... */

  chars_written = v3PrintAFile( file, (ascii *) "Error: %.*s\n",
                            v3u32u64( size ), output );

  if ( !v3u64Eq( chars_written, v3u64u32( 0 ) ) )
  {
    /* Error */
  }




    


    
    

      v3PrintUFile
    


    
Syntax



#include "cosmio.h"
u64 v3PrintUFile( v3_FILE * file, const unicode * format, ... );




    
Description

    

      Prints the formatted unicode text to the file. See
      v3PrintA for format usage.
    


    
Return Values

    

      Number of characters written to file.
    


    
Errors

    

      None.
    


    
Example



  unicode string[256];
  u64 chars_written;
  u64 size;
  v3_FILE * file;

  _V3_SET64( size, 00000000, 00000100 );

  /* ... */

  if ( v3StrCopyUA( string, (ascii *) "Test String.", size )
     != V3_PASS )
  {
    /* Error */
  }

  chars_written = v3PrintUFile( file, string );

  if ( v3u64Eq( chars_written, v3u64u32( 0 ) ) )
  {
    /* Error */
  }









  

    © Copyright Mithral Communications & Design Inc.
    
    1995-2003.
    All rights reserved.
    Mithral® and Cosm® are trademarks of
    Mithral Communications & Design Inc.
    

    
    Document last modified: May 22, 2003