B4P Reference

Function Names

str, soft, vstr, vsoft

Description

These functions convert variables of any type to strings, including void values. The function str returns strings as quoted strings whereas soft returns strings as softquoted strings. If only one parameter containing the value to provide, then following default rules are applied:

Original Type	Approach
boolean	Converts to true or false, using lower case letters
date	Converts to dates in text format using universal format YYYY-MM-DD, e.g 2020-12-31
numeral	Converts to numbers in text format using decimal point "." and without thousand spearators.
set	Converts to values arranged inside braces and separated with commas. Strings and dates are put into single quotation marks.
string	Contents stay unchanged
void	Converts to '# Invalid Value #', in case the void value does not come along with a different message inside '#' signs.

With the additional 1-3 parameters, specific formatting templates (patterns), options and placeholder characters can be applied. 2 approaches exist:

Direct Formatting using a formatting rule for a specific type, e.g. from date to string
Smart Formatting, providing different formatting rules to be applied automatically for the different types and, in some cases, value ranges.

Vectorization: The function names beginning with the prefix v support vectorization in the 1st function parameter. Instead of providing a single value, you can provide a set or even a nested set which contain multiple values. The function will then process every value and its return value contains a corresponding set containing all results.

Call as: function

Restrictions

Indirect parameter passing is disabled

Parameter count

1-4

Parameters

No.	Type	Description
1 input	all types set	Value to convert Value to check. With function vstr and vsoft, vectorization can be applied on the 1st function parameter if values are embedded in a set.
Opt. 2 input	string	Formatting template The formatting template is a string which containing patterns to convert a value of a specific type to a string. Different rules and patterns apply for the different types to convert. This means that you cannot use the same formatting template to convert a numeral to a string as well as a date to a string successfully because numeral formatting rules things like decimal points, number of digits behind decimal points, etc, where date formatting rules things like arranging date/month/year, using numbered or written months, time of day, etc. See next sections for details on formatting: String to String Formatting Parameters (accepts up to 4 function parameters) Numeral to String Formatting Parameters (accepts up to 4 function parameters) Date to String Formatting Parameters (accepts up to 3 function parameters) Boolean to String Formatting Parameters (accepts up to 3 function parameters) Set to String Formatting Parameters (accepts up to 2 function parameters) Void to String Formatting Parameters (accepts up to 4 function parameters) Default value: Default rules as described above are applied
Alt. 2 input	set	Smart formatting parameters In some cases, you wish to convert values of different types to string and need to apply different formatting templatess for them. In this case, put the following contents into a 2-level nested set and pass it as 2nd function parameter to this function. { Original data type, optionally a formatting template, optionally a formatting option or locale, and optionally a placeholder character }, like the function parameters described above and below. The function will first check the type of the data to convert, and then use the appropriate function call. Example: *str( 123.4, { { numeral, "#,###.00", en_US }, { date, "YYYY-MM-DD" }, { string, "### ### ### ", align right } } ); See next section on Smart Formatting Parameters for details. Default value:** Default rules as described above are applied
Opt. 3 input	set or string	Formatting option or locale For converting numerals, booleans and dates, a locale (related to countries and languages) information is expected. For formatting strings, voids and booleans , different formatting options apply and are described in the next sections. For sets, this 3rd and 4th function parameter are not supported. Locales can either be a combination of language and country (e.g. de_CH), or just a language or country name. Alternatively, specify 'local' for using the configured local country settings, or 'none' for using locale-independent formatting. All locale settings are not case sensitive, i.e. both 'germany' and 'GERMANY' are valid. Using locales (combined language and country) is highly recommended because common languages are spoken in many countries (e.g. 'english') and in several countries, multiple languages are supported (e.g. 'belgium', 'switzerland') in order to avoid ambiguities. Check the list of locales for available languages, countries and codes. Default value: For numbers, booleans and dates: 'none'
Opt. 4 input	string	Placeholder symbol Applicable to formatting numerals, strings and voids (which are converted to strings). In order to use these symbols, the formatting template (2nd function parameter) must provide space for them, e.g. with sufficient number of characters provided in string formatting, and use of question marks in number to string conversion. Default value: space symbol ' '

Return value

Type	Description
string set	Result Converted and formatted string. If Vectorization is used, then a set containing results is returned.

Examples

       echo( str( Abc ), ", ", str( 123.45 ), ", ", str(true) );

       echo( str(date('14.juillet.2020')), ", ", str( date('1. Aug 20 22:30')), ", ", str( time( '10:15' ) ) );

       echo( null() ); // void

       echo( {a,1,date(today),false} ); // void

Output

Abc, 123.45, true
2020-07-14, 2020-08-01 22:30:00, 10:15:00
# Invalid Value #
{'a',1,'2024-10-19',false}

Try it yourself: Open LIB_Function_str.b4p in B4P_Examples.zip. Decompress before use.