Cosm API - Input/Output and String Functions

[Cosm Logo]

Input/Output and String Functions

CosmInput
CosmInputRaw
CosmStrBytes
CosmStrCopy
CosmStrAppend
CosmStrCmp
CosmStrChar
CosmStrStr
Cosm{integral type}Str
Cosm{float type}Str
CosmPrint
CosmPrintStr
CosmPrintFile

CosmInput

Syntax

#include "cosm/os_io.h"
u32 CosmInput( utf8 * buffer, u32 max_bytes, u32 echo );

Description

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

Return Values

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

Errors

None.

Example

  utf8 buffer[256];
  u32 len;

  /* ... */

  len = CosmInput( buffer, 256, COSM_IO_ECHO );

  if ( len == -1 )
  {
    /* EOF */
  }

CosmInputRaw

Syntax

#include "cosm/os_io.h"
u32 CosmInputRaw( utf8 * buffer, u32 length, u32 echo );

Description

Read length bytes from stdin into the buffer. If echo is COSM_IO_NOECHO then the typed characters will not be echoed in any way (for password entry etc), otherwise echo should be COSM_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, 0xFFFFFFFF (-1) indicates EOF.

Errors

None.

Example

  utf8 * buffer;
  u32 size;
  u32 len;

  /* ... */

  CosmPrint( "Hit a key: " );
  len = CosmInputRaw( buffer, size, COSM_IO_ECHO );

  if ( ( len == -1 ) || ( len != 1 ) )
  {
    /* EOF reached */
  }

CosmStrBytes

Syntax

#include "cosm/os_io.h"
u32 CosmStrBytes( const utf8 * string );

Description

Get the length of the string pointed to by string.

Return Values

The length of the string in bytes.

Errors

None.

Example

  utf8 * string;
  u32 length;

  string = "A 22 byte test string.";

  length = CosmStrBytes( string );

CosmStrCopy

Syntax

#include "cosm/os_io.h"
s32 CosmStrCopy( utf8 * dest, const utf8 * src, u32 max_bytes );

Description

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

Return Values

COSM_PASS on success, or COSM_FAIL on failure.

Errors

Possible causes of an failure:

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

Example

  /* !!! */
  utf8 string[256];
  utf8 copy[256];
  u32 size;

  /* ... */

  if ( CosmStrCopy( copy, string, 256 ) != COSM_PASS )
  {
    /* Error */
  }

CosmStrAppend

Syntax

#include "cosm/os_io.h"
s32 CosmStrAppend( utf8 * stringA, const utf8 * stringB, u32 max_bytes );

Description

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

Return Values

COSM_PASS on success, or COSM_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_bytes-1

Example

  /* !!! */
  utf8 buffer[256];

  /* ... */

  if ( CosmStrAppend( buffer, "Test string", 256 )
     != COSM_PASS )
  {
    /* Error */
  }

CosmStrCmp

Syntax

#include "cosm/os_io.h"
s32 CosmStrCmp( const utf8 * stringA, const utf8 * stringB,
  u32 max_bytes );

Description

Compare the two Unicode strings, up to max_bytes or the end of one string.

Return Values

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

Errors

None.

Example

  utf8 stringa[128];
  utf8 stringb[128];
  u32 max;

  /* set stringa and stringb to something */

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

CosmStrChar

Syntax

#include "cosm/os_io.h"
utf8 * CosmStrChar( const utf8 * string, utf8 character,
  u32 max_bytes );

Description

Locate character in the string, which is up to max_bytes long.

Return Values

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

Errors

None.

Example

  utf8 string[128];
  utf8 * found;
  u32 max;

  /* read in string */

  if ( ( found = CosmStrChar( string, 'a', max ) ) != NULL )
  {
    /* the character 'a' is in the string at found */
  }

CosmStrStr

Syntax

#include "cosm/os_io.h"
utf8 * CosmStrStr( const utf8 * string, const utf8 * substring,
  u32 max_bytes );

Description

Locate substring in the string, which is up to max_bytes-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

Cosm{integral type}Str

Syntax

#include "cosm/os_io.h"
s32 CosmU32Str( u32 * result, utf8 ** end, const utf8 * string,
  u32 radix );
s32 CosmS32Str( s32 * result, utf8 ** end, const utf8 * string,
  u32 radix );
s32 CosmU64Str( u64 * result, utf8 ** end, const utf8 * string,
  u32 radix );
s32 CosmS64Str( s64 * result, utf8 ** end, const utf8 * string,
  u32 radix );
s32 CosmU128Str( u128 * result, utf8 ** end, const utf8 * string,
  u32 radix );
s32 CosmS128Str( s128 * result, utf8 ** end, const utf8 * 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 byte after the last byte used by 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 COSM_PASS on success, or sets result to 0 and returns COSM_FAIL on failure.

Errors

None.

Example

Cosm{float type}Str

Syntax

#include "cosm/os_io.h"
s32 Cosmf32Str( f32 * result, utf8 ** end, const utf8 * string );
s32 Cosmf64Str( f64 * result, utf8 ** end, const utf8 * 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 COSM_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 COSM_FAIL on failure.

Errors

None.

Example

CosmPrint

Syntax

#include "cosm/os_io.h"
u32 CosmPrint( const utf8 * format, ... );

Description

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

%[width][.prec]type_char

[width]

-n = min n characters are printed, left justify
0n = min n characters are printed, pad 0. No effect type s.
n = min n characters are printed, right justify.
* = next argument (u32) will specify width

[.prec]

.n = max n decimals places are printed for type f|F|g|G. Should always be set, default = 6, capped at 40.
.n = max n characters printed for type s|b. Default = 0. No effect on all other types.
.* = next argument (u32) will specify precision

[type_char]

c = single character
s = pointer to zero terminated string
b = pointer to raw byte buffer, precision flag is length in bytes
f = f32 or f64, [-]dddd.dddddd
F = f32 or f64, [-]d.dddddd[Edd]
g = f128, [-]dddd.dddddd
G = f128, [-]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

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 bytes output.

Errors

None.

Example

  utf8 * output;
  void * foo;
  u32 size;

  size = 256;
  output = CosmMemAlloc( (u64) size );

  /* ... */

  CosmPrint( "Error: %.*s\n", size, output );
  CosmPrint( "Size: %04u bytes\n", size );
  CosmPrint( "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

CosmPrintStr

Syntax

#include "cosm/os_io.h"
u32 CosmPrintStr( utf8 * string, u32 max_bytes,
  const utf8 * format, ... );

Description

Prints the formatted text to the string. No more than max_bytes-1 bytes will be written to the string. See CosmPrint for format usage.

Return Values

Number of bytes written to string, or -1 if truncated due to max_bytes.

Errors

None.

Example

  utf8 * output;
  void * foo;
  u32 chars_output;

  output = CosmMemAlloc( 256LL );

  /* ... */

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

  if ( chars_output == 0 )
  {
    /* Error */
  }

CosmPrintFile

Syntax

#include "cosm/os_io.h"
u32 CosmPrintFile( cosm_FILE * file, const utf8 * format, ... );

Description

Prints the formatted text to the file. See CosmPrint for format usage.

Return Values

Number of bytes written to file.

Errors

None.

Example

  utf8 * output;
  u32 chars_written;
  cosm_FILE * file;

  /* ... */

  chars_written = CosmPrintFile( file, "Error: %.*s\n",
    256, output );

  if ( chars_written == 0 )
  {
    /* Error */
  }