XCLE



String conversion module

Instructions manual


XCLE: eXtensible Concatenative Language Engine
Copyright (C) 2000-2006 Yann LANDRIN-SCHWEITZER a.k.a. Varkhan


This library is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published
by the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.

This library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this library; if not, write to the Free Software Foundation,
Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA


Author: Yann LANDRIN-SCHWEITZER
Contact: varkhan@varkhan.net
Homepage: http://www.varkhan.net/


Canonical object string representation


Function XCLE_ObjectToString

unsigned long XCLE_ObjectToString(XCLE_Object obj, char * out, unsigned long len) ;
Writes a character string representation of a generic object.

Args:
_ obj: object to write
_ out: output string (allocated for at least len+1 characters)
_ len: max number of characters to write


Returns:
_ -1: if some error occurred
_ the maximum number of characters needed to write completely the object if 'out' is NULL (len is ignored)
else the total number of characters written.


Errors:
_ EINVAL: if a NULL XCLE_Object was passed as argument



Function XCLE_VoidToString

unsigned long XCLE_VoidToString(XCLE_Void vd, char * out, unsigned long len) ;
Writes a Void object representation into a string: '¬'.

Args:
_ vd: Void object to write
_ out: output string
_ len: max number of characters to write, trailing '\0' excluded


Returns:
_ -1: if some error occured
_ 1: if 'out' was NULL or len>=1
_ 0: if 'out' was non-NULL and len was zero


Errors:
_ EINVAL: if a NULL Void was passed as argument



Function XCLE_IntgToString

unsigned long XCLE_IntgToString(XCLE_Intg in, char * out, unsigned long len) ;
Writes an Intg object representation into a character string.

Args:
_ in: Intg object to write
_ out: output string
_ len: maximum number of characters to write, trailing '\0' excluded


Returns:
_ NULL: if no memory was available
_ the number of characters needed to write an Intg, if 'out' was NULL
else the number of character written (10/11, or up to len).


Errors:
_ EINVAL: if a NULL Intg was passed as argument



Function XCLE_FltpToString

unsigned long XCLE_FltpToString(XCLE_Fltp fp, char * out, unsigned long len) ;
Writes a Fltp object representation into a character string.

Args:
_ fp: Fltp object to write
_ out: output string
_ len: maximum number of characters to write, trailing '\0' excluded


Returns:
_ NULL: if no memory was available
_ the maximum number of characters needed, if 'out' was NULL
else the number of characters written.


Errors:
_ EINVAL: if a NULL was passed as argument
_ ENOMEM: if no memory was available



Function XCLE_StrgToString

unsigned long XCLE_StrgToString(XCLE_Strg str, char * out, unsigned long len) ;
Writes a Strg object representation into a character string.

Args:
_ str
_ out
_ len


Returns:
_ NULL: if no memory was available


Errors:
_ EINVAL: if a NULL Strg was passed as argument
_ ENOMEM: if no memory was available



Function XCLE_ListToString

unsigned long XCLE_ListToString(XCLE_List lst, char * out, unsigned long len) ;
Writes a List object representation into a character string.

Args:
_ lst: List object to write
_ out: output character string (allocated for at least len+1 characters)
_ len: maximum number of characters to write


Returns:
_ -1: if a NULL List was passed as argument
_ the maximum number of characters neede to write this List, if 'out' was NULL
else the number of characters written.


Errors:
_ EINVAL: if a NULL List was passed as argument



Function XCLE_CodeToString

unsigned long XCLE_CodeToString(XCLE_Code cod, char * out, unsigned long len) ;
Writes a Code object representation into a character string.

Args:
_ cod: Code to write
_ out: output string (allocated for at least len+1 characters)
_ len: maximum number of character to write


Returns:
_ NULL: if a NULL Code was passed as argument
_ the number of characters neeede to write completely the Code, if 'out' was NULL
else the total number of characters written.


Errors:
_ EINVAL: if a NULL Code was passed as argument



Function XCLE_StackToString

unsigned long XCLE_StackToString(XCLE_Stack stk, char * out, unsigned long max, char * head, char * rowfmt, char * tail, unsigned long rows) ;
Prints the contents of an Stack, following the given formats.

Args:
_ stk: Stack to print
_ out: output character string
_ max: maximum number of characters to print (final nil char EXCEPTED)
_ head: head string
_ rowfmt: row printing format
_ tail: tail string
_ rows: number of rows (height in chars)


Returns:
_ -1: if the Stack was NULL
_ the total number of characters that should be printed, if 'out' was NULL.
else the number of characters printed.


Errors:
_ EINVAL: if a NULL Stack was passed as argument

Note:
The row format string is printed for each stack row between 0 and rows-1.
Escape sequences take the form %fdd..dd?, where the 'f' char is an optionnal
fill character (by dfault ' '), 'd' chars are digits and '?' denotes either
the 'n' or 's' characters. They are replaced by the stack row number, for the 'n'
format, and the corresponding object, for the 's' format, each written on
the number of chars denoted by the digits.




Function XCLE_HashToString

unsigned long XCLE_HashToString(XCLE_Hash nms, char * out, unsigned long max, char * head, char * rowfmt, char * tail) ;
Prints a Hash keys and contents, acording to formats.

Args:
_ nms: Hash to print
_ out: output character string
_ max: maximum number of characters to print (final nil char EXCEPTED)
_ head: head string
_ rowfmt: row printing format
_ tail: tail string
_ rows: number of rows (height in chars)


Returns:
_ -1: if the Hash was NULL
_ the total number of characters that should be printed, if 'out' was NULL.
else the number of characters printed.


Errors:
_ EINVAL: if a NULL Hash was passed as argument

Note:
The row format string is printed for each name entry in the Hash.
Escape sequences take the form %fdd..dd?, where the 'f' char is an optionnal
fill character (by dfault ' '), 'd' chars are digits and '?' denotes either
the 'n' or 's' characters. They are replaced by the entry name, for the 'n'
format, and the corresponding object, for the 's' format, each written on
the number of chars denoted by the digits.




Generated by textdoc2html - 2006-02-22