[[PageOutline]]

= Universal_String Reference (League.Strings) =

Universal_String is a base type to represent information in textual form as unbounded sequence of Unicode characters (Unicode code points). Several optimization techniques are used to optimize both space and performance characteristics.

== Operations ==

||=  Operation                               =||=  Description  =||
|| [#concatenation "&"]                       || Concatenate strings and characters ||
|| [#less "<"]                                || Compares two strings for binary less ||
|| [#lessequal "<="]                          || Compares two strings for binary less or equality ||
|| [#equal "="]                               || Compares two strings for binary equality ||
|| [#greater ">"]                             || Compares two strings for binary greater ||
|| [#greaterequal ">="]                       || Compares two strings for binary greater or equality ||
|| [#Append Append]                           || Appends string or character to the string ||
|| [#Clear Clear]                             || Clears the string ||
|| [#Collation Collation]                     || Computes sort key for string collation ||
|| [#Element Element]                         || Returns character at the specified position ||
|| [#Hash Hash]                               || Computes hash value for the string ||
|| [#Index Index]                             || Returns index of the first occurrence of the character in the string ||
|| [#Is_Empty Is_Empty]                       || Returns whether string is empty or not ||
|| [#Length Length]                           || Returns length of the string ||
|| [#Prepend Prepend]                         || Prepends string or character to the string ||
|| [#Replace Replace]                         || Replaces slice of the string by another string ||
|| [#Slice Slice]                             || Returns slice of the string ||
|| [#Split Split]                             || Splits tokens in the string into separate strings ||
|| [#To_Casefold To_Casefold]                 || Converts string into case folding form ||
|| [#To_Lowercase To_Lowercase]               || Converts string into lower case form ||
|| [#To_NFC To_NFC]                           || Converts string into Normalization Form C ||
|| [#To_NFD To_NFD]                           || Converts string into Normalization Form D ||
|| [#To_NFKC To_NFKC]                         || Converts string into Normalization Form KC ||
|| [#To_NFKD To_NFKD]                         || Converts string into Normalization Form KD ||
|| [#To_Uppercase To_Uppercase]               || Converts string into upper case form ||
|| [#To_Wide_Wide_String To_Wide_Wide_String] || Converts Universal_String into Wide_Wide_String ||

== Additional Subprograms ==

||=  Operation                               =||=  Description  =||
|| [#To_Universal_String To_Universal_String] || Converts Wide_Wide_String into Universal_String ||

== Detailed Description ==

=== "&" === #concatenation

{{{
   function "&"
    (Left  : Universal_String'Class;
     Right : Universal_String'Class) return Universal_String;

   function "&"
    (Left  : Universal_String'Class;
     Right : Universal_Character'Class) return Universal_String;

   function "&"
    (Left  : Universal_Character'Class;
     Right : Universal_String'Class) return Universal_String;

   function "&"
    (Left  : Universal_String'Class;
     Right : Wide_Wide_Character) return Universal_String;

   function "&"
    (Left  : Wide_Wide_Character;
     Right : Universal_String'Class) return Universal_String;

   function "&"
    (Left  : Universal_String'Class;
     Right : Wide_Wide_String) return Universal_String;

   function "&"
    (Left  : Wide_Wide_String;
     Right : Universal_String'Class) return Universal_String;
}}}

=== "<" === #less

{{{
   function "<"
    (Left  : Universal_String; Right : Universal_String) return Boolean;
}}}

=== "<=" === #lessequal

{{{
   function "<="
    (Left  : Universal_String; Right : Universal_String) return Boolean;
}}}

=== "=" === #equal

{{{
   overriding function "="
    (Left  : Universal_String; Right : Universal_String) return Boolean;
}}}

=== ">" === #greater

{{{
   function ">"
    (Left  : Universal_String; Right : Universal_String) return Boolean;
}}}

=== ">=" === #greaterequal

{{{
   function ">="
    (Left  : Universal_String; Right : Universal_String) return Boolean;
}}}

=== Append ===

{{{
   procedure Append
    (Self : in out Universal_String'Class;
     Item : Universal_String'Class);

   procedure Append
    (Self : in out Universal_String'Class;
     Item : Universal_Character'Class);

   procedure Append
    (Self : in out Universal_String'Class;
     Item : Wide_Wide_String);

   procedure Append
    (Self : in out Universal_String'Class;
     Item : Wide_Wide_Character);
}}}

=== Clear ===

{{{
   procedure Clear (Self : in out Universal_String'Class);
}}}

=== Collation ===

{{{
   function Collation (Self : Universal_String'Class) return Sort_Key;
}}}

=== Element ===

{{{
   function Element
    (Self  : Universal_String'Class;
     Index : Positive) return Universal_Character;
}}}

=== Hash ===

{{{
   function Hash (Self : Universal_String'Class) return Hash_Type;
}}}

=== Index ===

{{{
   function Index
    (Self      : Universal_String'Class;
     Character : Universal_Character'Class) return Natural;

   function Index
    (Self      : Universal_String'Class;
     Character : Wide_Wide_Character) return Natural;
}}}

=== Is_Empty ===

{{{
   function Is_Empty (Self : Universal_String'Class) return Boolean;
}}}

=== Length ===

{{{
   function Length (Self : Universal_String'Class) return Natural;
}}}

=== Prepend ===

{{{
   procedure Prepend
    (Self : in out Universal_String'Class;
     Item : Universal_String'Class);

   procedure Prepend
    (Self : in out Universal_String'Class;
     Item : Universal_Character'Class);

   procedure Prepend
    (Self : in out Universal_String'Class;
     Item : Wide_Wide_String);

   procedure Prepend
    (Self : in out Universal_String'Class;
     Item : Wide_Wide_Character);
}}}

=== Replace ===

{{{
   procedure Replace
    (Self : in out Universal_String'Class;
     Low  : Positive;
     High : Natural;
     By   : Universal_String'Class);

   procedure Replace
    (Self : in out Universal_String'Class;
     Low  : Positive;
     High : Natural;
     By   : Wide_Wide_String);
}}}

=== Slice ===

{{{
  function Slice
    (Self : Universal_String'Class;
     Low  : Positive;
     High : Natural) return Universal_String;
}}}

=== Split ===

{{{
   function Split
    (Self      : Universal_String'Class;
     Separator : Universal_Character'Class;
     Behavior  : Split_Behavior := Keep_Empty) return Universal_String_Vector;

   function Split
    (Self      : Universal_String'Class;
     Separator : Wide_Wide_Character;
     Behavior  : Split_Behavior := Keep_Empty) return Universal_String_Vector;
}}}

=== To_Casefold ===

{{{
   function To_Casefold
    (Self : Universal_String'Class) return Universal_String;
}}}

=== To_Lowercase ===

{{{
   function To_Lowercase
    (Self : Universal_String'Class) return Universal_String;
}}}

=== To_NFC ===

{{{
   function To_NFC (Self : Universal_String'Class) return Universal_String;
}}}

=== To_NFD ===

{{{
   function To_NFD (Self : Universal_String'Class) return Universal_String;
}}}

=== To_NFKC ===

{{{
   function To_NFKC (Self : Universal_String'Class) return Universal_String;
}}}

=== To_NFKD ===

{{{
   function To_NFKD (Self : Universal_String'Class) return Universal_String;
}}}

=== To_Universal_String ===

{{{
   function To_Universal_String 
    (Item : Wide_Wide_String) return Universal_String;
}}}

=== To_Uppercase ===

{{{
   function To_Uppercase
    (Self : Universal_String'Class) return Universal_String;
}}}

=== To_Wide_Wide_String ===

{{{
   function To_Wide_Wide_String 
    (Self : Universal_String'Class) return Wide_Wide_String;
}}}

== Optimization techniques ==

Textual representation of the information is used application widely, thus it is important to provide efficient implementation. 
Several optimization techniques are used for Universal_String implementation, below is list of most important.

1. Constant size of objects. Objects occupy constant size on the stack, independently of size of actual data. This is also important for multitasking application where size of the stack of each task is limited.
1. Copy-on-write. Data can be shared between several objects till it is not modified. This makes assignment operation to be constant time operation and minimize occupied memory.
1. UTF-16 encoding. Internally, data stored using UTF-16 encoding, which provides balance between memory use and performance.
1. SIMD optimization. On platforms where SIMD operations is available many string operations utilize special SIMD versions of algorithms.