AdaCL.EAstrings

More...

Entities

Constants and variables

Null_Converter
Null_Sequence

Simple types

Byte_Sequence
Conversion_Stop_Cause
Converter
EAstring_Array

Access types

Byte_Sequence_Access

Record types

EAstring
Null_EAstring
Null_String_Encoding

Subprograms

&
*
=
Adjust
Append
Byte_Sequence_To_Fake_String
Bytes
Close_Converter
Convert
Count
Delete
Delete
Encoding
Fake_String_To_Byte_Sequence
Finalize
Head
Head
Index
Index_Non_Blank
Initialize
Insert
Insert
Length
Open_Converter
Overwrite
Overwrite
Realloc_For_Chunk
Replace_Slice
Replace_Slice
Reset_Converter
Size
Slice
Tail
Tail
To_EAstring
To_EAstring
Transcode
Transcode
Transcode
Transcode
Trim
Trim

Nested packages

Character_Encodings
AF

Description

EAstring - encoding-aware string - is a dynamic string type similar to Ada.Strings.Unbounded.Unbounded_String, but it handles strings in all character encodings and frees you from character encoding troubles. It keeps track of how each string is encoded and transcodes them automatically when necessary. The child packages Latin_1 and UCS_2 contain subprograms for using EAstrings together with Ada's standard string types. Latin_1 is for String and Unbounded_String, and UCS_2 is for Wide_String and Unbounded_Wide_String. The child package IO provides encoding-aware input and output. The child package OS and its descendants provide encoding-aware access to information from the environment. The procedures and functions that manipulate EAstrings will transcode them as needed. The procedures may change the encoding of their parameters when these are declared "in out". The functions will leave their parameters unchanged but may return EAstrings in other encodings. There are also subprograms available that allow for explicit transcoding (Transcode and Convert). In most cases it should not be necessary to use them, but if you need to convert an EAstring to a byte sequence in a particular encoding you should call Transcode to make sure that it is in the right encoding, and then retrieve the byte sequence with Bytes. You may also want to call Transcode for performance reasons in certain cases. A series of function calls may lead to the same string being transcoded over and over, and this can be prevented by explicitly transcoding it first. The first character in an EAstring always has the index 1. In this package, a character is a Unicode code point; not a byte, a code unit or a grapheme. In some encodings, a code unit is one byte. In others it's two or four bytes. In some encodings, one character (code point) can be encoded in several code units. A grapheme can be represented as one character or as a base character followed by one or more combining characters. Most of the subprograms in this package count, compare and process code points. A few deal with bytes. Througout the EAstrings library, it is assumed that a byte is eight bits.

Null_Converter [source]

111Null_Converter : constant Converter;

Null_Sequence [source]

720Null_Sequence : aliased Byte_Sequence := [1 .. 0 => 0];

Byte_Sequence [source]

88 type Byte_Sequence is
89 array (Positive range <>) of aliased Interfaces.Unsigned_8;

Conversion_Stop_Cause [source]

94 type Conversion_Stop_Cause is (
95 All_Done,
96 Target_Full,
97 Incomplete,
98 Inconvertible);

Reason why Convert returns. All_Done : The whole input string was converted. Target_Full : There isn't enough room in the target. Incomplete : The source ends in an incomplete code sequence. Inconvertible : One of these errors happened:

11: The source isn't a valid encoded string for the
2 source encoding.
32: The source contains a character that can't be
4 represented in the target encoding.
All_Done
Target_Full
Incomplete
Inconvertible

Converter [source]

92 type Converter is private;

EAstring_Array [source]

86 type EAstring_Array is array (Integer range <>) of EAstring;

Byte_Sequence_Access [source]

726 type Byte_Sequence_Access is access all Byte_Sequence;

EAstring [source]

84 type EAstring is private;

Null_EAstring [source]

109 -- Reason why Convert returns.
110 -- All_Done : The whole input string was converted.
111 -- Target_Full : There isn't enough room in the target.
112 -- Incomplete : The source ends in an incomplete code sequence.
113 -- Inconvertible : One of these errors happened:
114 -- 1: The source isn't a valid encoded string for the
115 -- source encoding.
116 -- 2: The source contains a character that can't be
117 -- represented in the target encoding.
118
119 Null_EAstring : constant EAstring;

Null_String_Encoding [source]

722 Null_String_Encoding : constant Character_Encoding := US_ASCII;

The null string is set to the least demanding encoding to avoid unnecessarily transcoding other strings.

& [source]

131 function "&" (Left, Right : in EAstring) return EAstring;

Concatenates two EAstrings.

Left of type AdaCL.EAstrings.EAstring
Right of type AdaCL.EAstrings.EAstring
Return value

* [source]

402 function "*" (Left : in Natural; Right : in EAstring) return EAstring;

Returns an EAstring that comprises Left concatenated copies of Right.

Left of type Natural
Right of type AdaCL.EAstrings.EAstring
Return value

= [source]

143 overriding function "=" (Left, Right : in EAstring) return Boolean;

Returns True if and only if Left and Right contain identical sequences of characters (regardless of their current encodings).

Left of type AdaCL.EAstrings.EAstring
Right of type AdaCL.EAstrings.EAstring
Return value

Adjust [source]

746 overriding procedure Adjust (Object : in out EAstring);
Object of type AdaCL.EAstrings.EAstring

Append [source]

128 procedure Append (Source : in out EAstring; New_Item : in EAstring);

Appends New_Item to the end of Source.

Source of type AdaCL.EAstrings.EAstring
New_Item of type AdaCL.EAstrings.EAstring

Byte_Sequence_To_Fake_String [source]

672 function Byte_Sequence_To_Fake_String
673 (Source : in Byte_Sequence)
674 return String;

Unchecked conversion of Byte_Sequence to String. The result will not be a real String (unless the byte sequence happens to be in Latin 1). For passing strings to functions that take String parameters but interpret them as some other encoding.

Source of type AdaCL.EAstrings.Byte_Sequence
Return value

Bytes [source]

664 function Bytes (Source : in EAstring) return Byte_Sequence;

Returns the byte sequence that an EAstring is encoded as in its current encoding.

Source of type AdaCL.EAstrings.EAstring
Return value

Close_Converter [source]

651 procedure Close_Converter (Item : in out Converter);

Frees a converter object allocated by Open_Converter.

Item of type AdaCL.EAstrings.Converter

Convert [source]

634 procedure Convert
635 (State : in Converter;
636 Source : in Byte_Sequence;
637 Target : out Byte_Sequence;
638 Source_Last : out Natural;
639 Target_Last : out Natural;
640 Cause : out Conversion_Stop_Cause);

State must be a converter object allocated by Open_Converter. Source must be a string encoded in the encoding that this converter converts from. The string is converted and stored in Target. The indices in Source and in Target of the last byte of the last character that was converted are stored in Source_Last and Target_Last, respectively. The reason why Convert stopped is reported in Cause.

State of type AdaCL.EAstrings.Converter
Source of type AdaCL.EAstrings.Byte_Sequence
Target of type AdaCL.EAstrings.Byte_Sequence
Source_Last of type Natural
Target_Last of type Natural
Cause of type AdaCL.EAstrings.Conversion_Stop_Cause

Count [source]

236 function Count
237 (Source : in EAstring;
238 Pattern : in EAstring)
239 -- Mapping : in Maps.Character_Mapping := Maps.Identity) to be added
240 -- later
241 return Natural;

Returns the maximum number of nonoverlapping slices of Source that match Pattern with respect to Mapping. If Pattern is the null string then Pattern_Error is propagated.

Source of type AdaCL.EAstrings.EAstring
Pattern of type AdaCL.EAstrings.EAstring
Return value

Delete [source]

341 function Delete
342 (Source : in EAstring;
343 From : in Positive;
344 Through : in Natural)
345 return EAstring;

Returns Replace_Slice(Source, From, Through, Null_EAstring).

Source of type AdaCL.EAstrings.EAstring
From of type Positive
Through of type Natural
Return value

Delete [source]

348 procedure Delete
349 (Source : in out EAstring;
350 From : in Positive;
351 Through : in Natural);

Like above, but changes Source instead of returning a new string.

Source of type AdaCL.EAstrings.EAstring
From of type Positive
Through of type Natural

Encoding [source]

661 function Encoding (Source : in EAstring) return Character_Encoding;

Returns the encoding that an EAstring is currently encoded in.

Source of type AdaCL.EAstrings.EAstring
Return value

Fake_String_To_Byte_Sequence [source]

680 function Fake_String_To_Byte_Sequence
681 (Source : in String)
682 return Byte_Sequence;

Unchecked conversion of String to Byte_Sequence. For making EAstrings from objects that are declared as String but contain some other encoding than Latin 1.

Source of type String
Return value

Finalize [source]

747 overriding procedure Finalize (Object : in out EAstring);
Object of type AdaCL.EAstrings.EAstring

Head [source]

376 function Head
377 (Source : in EAstring;
378 Count : in Natural)
379 -- : in Unicode_Character := Space" to be added later.
380 return EAstring;

Returns an EAstring of length Count. If Count <= Length(Source), the string comprises the first Count characters of Source. Otherwise its contents are Source concatenated with Count - Length(Source) spaces.

Source of type AdaCL.EAstrings.EAstring
Count of type Natural
Return value

Head [source]

385 procedure Head (Source : in out EAstring; Count : in Natural);

"Pad : in Unicode_Character := Space" to be added later. Like above, but changes Source instead of returning a new string.

Source of type AdaCL.EAstrings.EAstring
Count of type Natural

Index [source]

199 function Index
200 (Source : in EAstring;
201 Pattern : in EAstring;
202 Going : in Direction := Forward)
203 -- Mapping : in Maps.Character_Mapping := Maps.Identity) to be added
204 -- later
205 return Natural;

Searches for a slice of Source, with the same length as Pattern, that matches Pattern with respect to Mapping. The parameter Going indicates the direction of the lookup. Index returns the smallest (if Going = Forward) or largest (if Going = Backward) index I such that the slice of Source starting at I matches Pattern. If there is no such slice, then 0 is returned. If Pattern is the null string then Pattern_Error is propagated.

Source of type AdaCL.EAstrings.EAstring
Pattern of type AdaCL.EAstrings.EAstring
Going of type Direction
Return value

Index_Non_Blank [source]

228 function Index_Non_Blank
229 (Source : in EAstring;
230 Going : in Direction := Forward)
231 return Natural;

Returns the index of the first (if Going = Forward) or last (if Going = Backward) character in Source that is not a space (U+0020). If there is no such character, then 0 is returned.

Source of type AdaCL.EAstrings.EAstring
Going of type Direction
Return value

Initialize [source]

745 overriding procedure Initialize (Object : in out EAstring);
Object of type AdaCL.EAstrings.EAstring

Insert [source]

308 function Insert
309 (Source : in EAstring;
310 Before : in Positive;
311 New_Item : in EAstring)
312 return EAstring;

Propagates Index_Error if Before > Length(Source)+1; otherwise returns Slice(Source, 1, Before-1) & New_Item & Slice(Source, Before, Length(Source)).

Source of type AdaCL.EAstrings.EAstring
Before of type Positive
New_Item of type AdaCL.EAstrings.EAstring
Return value

Insert [source]

317 procedure Insert
318 (Source : in out EAstring;
319 Before : in Positive;
320 New_Item : in EAstring);

Like above, but changes Source instead of returning a new string.

Source of type AdaCL.EAstrings.EAstring
Before of type Positive
New_Item of type AdaCL.EAstrings.EAstring

Length [source]

117 function Length (Source : EAstring) return Natural;

Returns the number of characters in the string. (This is not the same as the space it will take when printed, even in a fixed-width font.) This may be a more expensive operation than one might think, because if the string is in a variable-width encoding, a copy of it must be converted to a fixed-width encoding before the characters can be counted.

Source of type AdaCL.EAstrings.EAstring
Return value

Open_Converter [source]

626 function Open_Converter
627 (From, To : Character_Encoding)
628 return Converter;

Returns a freshly allocated converter object that converts text from the encoding given in From to the one in To. The converter must be freed with Close_Converter. Unsupported_Conversion is raised if the operating system doesn't support this conversion.

From of type AdaCL.EAstrings.Character_Encodings.Character_Encoding
To of type AdaCL.EAstrings.Character_Encodings.Character_Encoding
Return value

Overwrite [source]

323 function Overwrite
324 (Source : in EAstring;
325 Position : in Positive;
326 New_Item : in EAstring)
327 return EAstring;

Propagates Index_Error if Position > Length(Source)+1; otherwise returns the string obtained from Source by consecutively replacing characters starting at Position with corresponding characters from New_Item. If the end of Source is reached before the characters in New_Item are exhausted, the remaining characters from New_Item are appended to the string.

Source of type AdaCL.EAstrings.EAstring
Position of type Positive
New_Item of type AdaCL.EAstrings.EAstring
Return value

Overwrite [source]

335 procedure Overwrite
336 (Source : in out EAstring;
337 Position : in Positive;
338 New_Item : in EAstring);

Like above, but changes Source instead of returning a new string.

Source of type AdaCL.EAstrings.EAstring
Position of type Positive
New_Item of type AdaCL.EAstrings.EAstring

Realloc_For_Chunk [source]

749 procedure Realloc_For_Chunk
750 (Source : in out EAstring;
751 Chunk_Size : Natural);
Source of type AdaCL.EAstrings.EAstring
Chunk_Size of type Natural

Replace_Slice [source]

290 function Replace_Slice
291 (Source : in EAstring;
292 Low : in Positive;
293 High : in Natural;
294 By : in EAstring)
295 return EAstring;

If Low > Length(Source)+1, then Index_Error is propagated. Otherwise: � If High >= Low, then the returned string comprises Slice(Source, 1, Low-1) & By & Slice(Source, High+1, Length(Source)). � If High < Low, then the returned string is Insert(Source, Low, By).

Source of type AdaCL.EAstrings.EAstring
Low of type Positive
High of type Natural
By of type AdaCL.EAstrings.EAstring
Return value

Replace_Slice [source]

301 procedure Replace_Slice
302 (Source : in out EAstring;
303 Low : in Positive;
304 High : in Natural;
305 By : in EAstring);

Like above, but changes Source instead of returning a new string.

Source of type AdaCL.EAstrings.EAstring
Low of type Positive
High of type Natural
By of type AdaCL.EAstrings.EAstring

Reset_Converter [source]

648 procedure Reset_Converter (Item : in Converter);

Resets a converter object to its initial state.

Item of type AdaCL.EAstrings.Converter

Size [source]

668 function Size (Source : EAstring) return Natural;

Returns the number of bytes in the byte sequence that the string is currently encoded as.

Source of type AdaCL.EAstrings.EAstring
Return value

Slice [source]

134 function Slice
135 (Source : in EAstring;
136 Low : in Positive;
137 High : in Natural)
138 return EAstring;

Slice returns the characters Low through High in Source. It returns Null_EAstring if Low > High, and raises Index_Error if Low <= High and High > Length(Source).

Source of type AdaCL.EAstrings.EAstring
Low of type Positive
High of type Natural
Return value

Tail [source]

389 function Tail
390 (Source : in EAstring;
391 Count : in Natural)
392 -- : in Unicode_Character := Space" to be added later.
393 return EAstring;

Returns an EAstring of length Count. If Count <= Length(Source), the string comprises the last Count characters of Source. Otherwise its contents are Count - Length(Source) spaces concatenated with Source.

Source of type AdaCL.EAstrings.EAstring
Count of type Natural
Return value

Tail [source]

398 procedure Tail (Source : in out EAstring; Count : in Natural);

"Pad : in Unicode_Character := Space" to be added later. Like above, but changes Source instead of returning a new string.

Source of type AdaCL.EAstrings.EAstring
Count of type Natural

To_EAstring [source]

125 function To_EAstring (Length : in Natural) return EAstring;

Returns a string of Length spaces.

Length of type Natural
Return value

To_EAstring [source]

654 function To_EAstring
655 (Source : in Byte_Sequence;
656 Encoding : in Character_Encoding)
657 return EAstring;

Constructs an EAstring from a byte sequence and a character encoding. Source had better be a valid encoded text in Encoding.

Source of type AdaCL.EAstrings.Byte_Sequence
Encoding of type AdaCL.EAstrings.Character_Encodings.Character_Encoding
Return value

Transcode [source]

604 function Transcode
605 (Source : in EAstring;
606 New_Encoding : in Character_Encoding)
607 return EAstring;

Returns a copy of Source encoded in New_Encoding.

Source of type AdaCL.EAstrings.EAstring
New_Encoding of type AdaCL.EAstrings.Character_Encodings.Character_Encoding
Return value

Transcode [source]

610 procedure Transcode
611 (Source : in out EAstring;
612 New_Encoding : in Character_Encoding);

Makes sure that Source is encoded in New_Encoding.

Source of type AdaCL.EAstrings.EAstring
New_Encoding of type AdaCL.EAstrings.Character_Encodings.Character_Encoding

Transcode [source]

615 function Transcode
616 (Source : in EAstring_Array;
617 New_Encoding : in Character_Encoding)
618 return EAstring_Array;

Returns a copy of Source where each string is encoded in New_Encoding.

Source of type AdaCL.EAstrings.EAstring_Array
New_Encoding of type AdaCL.EAstrings.Character_Encodings.Character_Encoding
Return value

Transcode [source]

621 procedure Transcode
622 (Source : in out EAstring_Array;
623 New_Encoding : in Character_Encoding);

Makes sure that each string in Source is encoded in New_Encoding.

Source of type AdaCL.EAstrings.EAstring_Array
New_Encoding of type AdaCL.EAstrings.Character_Encodings.Character_Encoding

Trim [source]

354 function Trim
355 (Source : in EAstring;
356 Side : in Trim_End)
357 return EAstring;

Returns the EAstring obtained by removing from Source all leading (if Side = Left), trailing (if Side = Right), or leading and trailing (if Side = Both) space characters (U+0020).

Source of type AdaCL.EAstrings.EAstring
Side of type Trim_End
Return value

Trim [source]

362 procedure Trim (Source : in out EAstring; Side : in Trim_End);

Like above, but changes Source instead of returning a new string.

Source of type AdaCL.EAstrings.EAstring
Side of type Trim_End