/***************************************************************************************************
# UNIVERSAL STRING PRIMITIVES:
# --------------------------------------------------------------------------------------------------
# SQLAUX scripting library | Author: Sergei Y.Kitáev
# -- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/

/*==================================================================================================
# STRING LENGTH (CONSIDERING ENDING SPACES):
# === Usage: ===
# dbo.[AUX:StrLength]( <String> )
*/
function [AUX:StrLength]( @String $(dt_String_AUX) )
returns int


/*==================================================================================================
# TRIMMING OF BOUNDING SPACES (PROCEDURE):
# === Usage: ===
# exec [AUX:TrimSpaces] @<String variable> out
*/
procedure [AUX:TrimSpaces] @String $(dt_String_AUX) out
/*==================================================================================================
# TRIMMING OF TAIL SPACES (PROCEDURE):
# === Usage: ===
# exec [AUX:TrimEndingSpaces] @<String variable> out
*/
procedure [AUX:TrimEndingSpaces] @String $(dt_String_AUX) out


/*==================================================================================================
# SUBSTITUTION OF EMPTY STRING WITH NULL:
# === Usage: ===
# dbo.[AUX:EmptyAsNull]( <String> )
*/
function [AUX:EmptyAsNull]( @String $(dt_String_AUX) )
returns $(dt_String_AUX)
/*==================================================================================================
# EMPTY STRING SUBSTITUTION WITH NULL (PROCEDURE):
# === Usage: ===
# exec [AUX:SubstEmptyWithNull] @<String variable> out
*/
procedure [AUX:SubstEmptyWithNull] @String $(dt_String_AUX) out


/*==================================================================================================
# STRING COMPLEMENT FROM START (WITH SPACES):
# === Usage: ===
# dbo.[AUX:PadStart]( <String>, <Width for padding> )
*/
function [AUX:PadStart]( @String $(dt_String_AUX), @WidthForPadding int )
returns $(dt_String_AUX)
/*==================================================================================================
# STRING COMPLEMENT FROM END (WITH SPACES):
# === Usage: ===
# dbo.[AUX:PadEnd]( <String>, <Width for padding> )
*/
function [AUX:PadEnd]( @String $(dt_String_AUX), @WidthForPadding int )
returns $(dt_String_AUX)

/*==================================================================================================
# STRING COMPLEMENT FROM START, WITH PADDING CHAR OR WITH SPACES (EXT.VERSION):
# === Usage: ===
# dbo.[AUX:PadStart.Ext]( <String>, <Width for padding>, null )
# dbo.[AUX:PadStart.Ext]( <String>, <Width for padding>, <Padding character> )
*/
function [AUX:PadStart.Ext]( @String $(dt_String_AUX),
                             @WidthForPadding int,
                             @PadChar nchar )
returns $(dt_String_AUX)
/*==================================================================================================
# STRING COMPLEMENT FROM END, WITH PADDING CHAR OR WITH SPACES (EXT.VERSION):
# === Usage: ===
# dbo.[AUX:PadEnd.Ext]( <String>, <Width for padding>, null )
# dbo.[AUX:PadEnd.Ext]( <String>, <Width for padding>, <Padding character> )
*/
function [AUX:PadEnd.Ext]( @String $(dt_String_AUX),
                           @WidthForPadding int,
                           @PadChar nchar )
returns $(dt_String_AUX)


/*==================================================================================================
# STRING COMPLEMENT WITH ZERO, BY WIDTH OF ABSOLUTE VALUE (WITHOUT MINUS SIGN):
# === Usage: ===
# dbo.[AUX:ZeroLeftPadByWidthOfAbs]( <String>, <Width without head minus> )
*/
function [AUX:ZeroLeftPadByWidthOfAbs]( @String $(dt_String_AUX),
                                        @WidthWithoutHeadMinus int )
returns $(dt_String_AUX)


/*==================================================================================================
# CHECKING, IF STRING STARTS FROM SPACE:
# === Usage: ===
# dbo.[AUX:StartsFromSpace]( <String> )
*/
function [AUX:StartsFromSpace]( @String $(dt_String_AUX) )
returns bit
/*==================================================================================================
# CHECKING, IF STRING STARTS FROM SPACE (EXT.VERSION):
# === Usage: ===
# dbo.[AUX:StartsFromSpace.Ext]( <String>, 1 )
# dbo.[AUX:StartsFromSpace.Ext]( <String>, 0 )
==================================================================================================*/
function [AUX:StartsFromSpace.Ext]( @String $(dt_String_AUX), @TreatBlankAsEmpty bit=0 )
returns bit

/*==================================================================================================
# CHECKING, IF STRING CONTAINS SIGNIFICANT (NON-TRAILING) SPACES:
# === Usage: ===
# dbo.[AUX:HasSignificantSpaces]( <String> )
*/
function [AUX:HasSignificantSpaces]( @String $(dt_String_AUX) )
returns bit

/*==================================================================================================
# CHECKING, IF CHARACTER BELONGS TO DECIMAL DIGITS ('0','1',...'9'):
# === Usage: ===
# dbo.[AUX:IsDigit]( <Character> )
*/
function [AUX:IsDigit]( @Char nchar )
returns bit


/*==================================================================================================
# CONCATENATION OF TWO STRINGS THROUGH SEPARATOR (THROUGH COMMA BY DEFAULT):
# === Usage: ===
# dbo.[AUX:ThroughSeparator]( <String-1>, <String-2>, <Separator> )
*/
function [AUX:ThroughSeparator]( @String_1 $(dt_String_AUX),
                                 @String_2 $(dt_String_AUX),
                                 @Separator $(dt_String_AUX) = null )
returns $(dt_String_AUX)
/*==================================================================================================
# CONCATENATION OF THREE STRINGS THROUGH SEPARATOR (THROUGH COMMA BY DEFAULT):
# === Usage: ===
# dbo.[AUX:ThroughSeparator_3]( <Separator>, <String-1>, <String-2>, <String-3> )
*/
function [AUX:ThroughSeparator_3]( @Separator $(dt_String_AUX) = null,
                                   @String_1 $(dt_String_AUX),
                                   @String_2 $(dt_String_AUX),
                                   @String_3 $(dt_String_AUX) )
returns $(dt_String_AUX)
/*==================================================================================================
# CONCATENATION OF FOUR STRINGS THROUGH SEPARATOR (THROUGH COMMA BY DEFAULT):
# === Usage: ===
# dbo.[AUX:ThroughSeparator_4]( <Separator>, <String-1>, <String-2>, <String-3>, <String-4> )
*/
function [AUX:ThroughSeparator_4]( @Separator $(dt_String_AUX) = null,
                                   @String_1 $(dt_String_AUX),
                                   @String_2 $(dt_String_AUX),
                                   @String_3 $(dt_String_AUX),
                                   @String_4 $(dt_String_AUX) )
returns $(dt_String_AUX)
/*==================================================================================================
# CONCATENATION OF FIVE STRINGS THROUGH SEPARATOR (THROUGH COMMA BY DEFAULT):
# === Usage: ===
# dbo.[AUX:ThroughSeparator_5]( <Separator>,
#                             <String-1>, <String-2>, <String-3>, <String-4>, <String-5> )
*/
function [AUX:ThroughSeparator_5]( @Separator $(dt_String_AUX) = null,
                                   @String_1 $(dt_String_AUX),
                                   @String_2 $(dt_String_AUX),
                                   @String_3 $(dt_String_AUX),
                                   @String_4 $(dt_String_AUX),
                                   @String_5 $(dt_String_AUX) )
returns $(dt_String_AUX)


/*==================================================================================================
# CONCATENATION OF TWO STRINGS THROUGH COMMA:
# === Usage: ===
# dbo.[AUX:ThroughComma]( <String-1>, <String-2> )
*/
function [AUX:ThroughComma]( @String_1 $(dt_String_AUX),
                             @String_2 $(dt_String_AUX) )
returns $(dt_String_AUX)
/*==================================================================================================
# CONCATENATION OF THREE STRINGS THROUGH COMMA:
# === Usage: ===
# dbo.[AUX:ThroughComma_3]( <String-1>, <String-2>, <String-3> )
*/
function [AUX:ThroughComma_3]( @String_1 $(dt_String_AUX),
                               @String_2 $(dt_String_AUX),
                               @String_3 $(dt_String_AUX) )
returns $(dt_String_AUX)
/*==================================================================================================
# CONCATENATION OF FOUR STRINGS THROUGH COMMA:
# === Usage: ===
# dbo.[AUX:ThroughComma_4]( <String-1>, <String-2>, <String-3>, <String-4> )
*/
function [AUX:ThroughComma_4]( @String_1 $(dt_String_AUX),
                               @String_2 $(dt_String_AUX),
                               @String_3 $(dt_String_AUX),
                               @String_4 $(dt_String_AUX) )
returns $(dt_String_AUX)
/*==================================================================================================
# CONCATENATION OF FIVE STRINGS THROUGH COMMA:
# === Usage: ===
# dbo.[AUX:ThroughComma_5]( <String-1>, <String-2>, <String-3>, <String-4>, <String-5> )
*/
function [AUX:ThroughComma_5]( @String_1 $(dt_String_AUX),
                               @String_2 $(dt_String_AUX),
                               @String_3 $(dt_String_AUX),
                               @String_4 $(dt_String_AUX),
                               @String_5 $(dt_String_AUX) )
returns $(dt_String_AUX)


/*==================================================================================================
# CONCATENATION OF TWO STRINGS THROUGH COMMA AND SPACE:
# === Usage: ===
# dbo.[AUX:ThroughCommaAndSpace]( <String-1>, <String-2> )
*/
function [AUX:ThroughCommaAndSpace]( @String_1 $(dt_String_AUX),
                                     @String_2 $(dt_String_AUX) )
returns $(dt_String_AUX)
/*==================================================================================================
# CONCATENATION OF THREE STRINGS THROUGH COMMA AND SPACE:
# === Usage: ===
# dbo.[AUX:ThroughCommaAndSpace_3]( <String-1>, <String-2>, <String-3> )
*/
function [AUX:ThroughCommaAndSpace_3]( @String_1 $(dt_String_AUX),
                                       @String_2 $(dt_String_AUX),
                                       @String_3 $(dt_String_AUX) )
returns $(dt_String_AUX)
/*==================================================================================================
# CONCATENATION OF FOUR STRINGS THROUGH COMMA AND SPACE:
# === Usage: ===
# dbo.[AUX:ThroughCommaAndSpace_4]( <String-1>, <String-2>, <String-3>, <String-4> )
*/
function [AUX:ThroughCommaAndSpace_4]( @String_1 $(dt_String_AUX),
                                       @String_2 $(dt_String_AUX),
                                       @String_3 $(dt_String_AUX),
                                       @String_4 $(dt_String_AUX) )
returns $(dt_String_AUX)
/*==================================================================================================
# CONCATENATION OF FIVE STRINGS THROUGH COMMA AND SPACE:
# === Usage: ===
# dbo.[AUX:ThroughCommaAndSpace_5]( <String-1>, <String-2>, <String-3>, <String-4>, <String-5> )
*/
function [AUX:ThroughCommaAndSpace_5]( @String_1 $(dt_String_AUX),
                                       @String_2 $(dt_String_AUX),
                                       @String_3 $(dt_String_AUX),
                                       @String_4 $(dt_String_AUX),
                                       @String_5 $(dt_String_AUX) )
returns $(dt_String_AUX)


/*==================================================================================================
# TEXT TRANSFORMATION (OF STRINGS, CONCATENATED THROUGH CR+LF) TO SINGLE LINE (WITHOUT LINE FEEDS):
# === Usage: ===
# dbo.[AUX:ToSingleLine]( <String with CR-n-LFs> )
*/
function [AUX:ToSingleLine]( @Text $(dt_String_AUX) )
returns $(dt_String_AUX)
