strings_bounded

extras_2008/strings_bounded.vhdl

Dependencies

strings, strings_maps, strings_maps_constants, strings_fixed

Description

This package provides a string library for operating on bounded length strings. This is a clone of the Ada‘95 library Ada.Strings.Bounded. It is a nearly complete implementation with only the procedures taking character mapping functions omitted because of VHDL limitations. This package requires support for VHDL-2008 package generics. The maximum size of a bounded string is established by instantiating a new package with the MAX generic set to the desired size.

Unlike fixed length strings which must always be padded to their full length, bounded strings can have any length up to the maximum set when the package is instantiated.

Example usage

-- Instantiate the package with a maximum length
library extras_2008;
package s20 is new extras_2008.strings_bounded
  generic map(MAX => 20);
use work.s20.all;
...
variable str : bounded_string; -- String with up to 20 characters
variable l   : natural;
...
str := to_bounded_string("abc");
l := length(str); -- returns 3
append(str, "def");
l := length(str); -- returns 6

Types

strings_bounded.bounded_string

Bounded string object.

Subtypes

strings_bounded.length_range

String length constrained to maximum length set by the MAX package generic.

Subprograms

strings_bounded.length (source : bounded_string) → length_range

Return the length of a bounded_string.

Parameters:

• source (bounded_string) – String to check length of

Returns:

Length of the string.

strings_bounded.to_bounded_string (source : string; drop : truncation := error) → bounded_string

Convert a string to bounded_string.

Parameters:

• source (string) – String to convert
• drop (truncation) – Truncation behavior for longer strings

Returns:

Converted string.

strings_bounded.to_string (source : bounded_string) → string

Convert a bounded_string to string.

Parameters:

• source (bounded_string) – String to convert

Returns:

Bounded string converted to a plain string.

strings_bounded.append (l : bounded_string; r : bounded_string; drop : truncation := error) → bounded_string

Append two bounded_strings.

Parameters:

• l (bounded_string) – Left string
• r (bounded_string) – Right string
• drop (truncation) – Truncation behavior for longer strings

Returns:

String with l and r concatenated.

strings_bounded.append (l : bounded_string; r : string; drop : truncation := error) → bounded_string

Append a string to a bounded_string.

Parameters:

• l (bounded_string) – Left string
• r (string) – Right string
• drop (truncation) – Truncation behavior for longer strings

Returns:

String with l and r concatenated.

strings_bounded.append (l : string; r : bounded_string; drop : truncation := error) → bounded_string

Append a bounded_string to a string.

Parameters:

• l (string) – Left string
• r (bounded_string) – Right string
• drop (truncation) – Truncation behavior for longer strings

Returns:

String with l and r concatenated.

strings_bounded.append (l : bounded_string; r : character; drop : truncation := error) → bounded_string

Append a character to a bounded_string.

Parameters:

• l (bounded_string) – Left string
• r (character) – Right character
• drop (truncation) – Truncation behavior for longer strings

Returns:

String with l and r concatenated.

strings_bounded.append (l : character; r : bounded_string; drop : truncation := error) → bounded_string

Append a bounded_string to a character.

Parameters:

• l (character) – Left character
• r (bounded_string) – Right string
• drop (truncation) – Truncation behavior for longer strings

Returns:

String with l and r concatenated.

strings_bounded.append (source : inout bounded_string; new_item : in bounded_string; drop : in truncation := error)

Append a bounded_string.

Parameters:

• source (inout bounded_string) – String to append onto
• new_item (in bounded_string) – String to append
• drop (in truncation) – Truncation behavior for longer strings

strings_bounded.append (source : inout bounded_string; new_item : in string; drop : in truncation := error)

Append a string.

Parameters:

• source (inout bounded_string) – String to append onto
• new_item (in string) – String to append
• drop (in truncation) – Truncation behavior for longer strings

strings_bounded.append (source : inout bounded_string; new_item : in character; drop : in truncation := error)

Append a character.

Parameters:

• source (inout bounded_string) – String to append onto
• new_item (in character) – Character to append
• drop (in truncation) – Truncation behavior for longer strings

strings_bounded."&" (l : bounded_string; r : bounded_string) → bounded_string

Concatenate two strings.

Parameters:

• l (bounded_string) – Left string
• r (bounded_string) – Right string

Returns:

String with l and r concatenated.

strings_bounded."&" (l : bounded_string; r : string) → bounded_string

Concatenate a string to a bounded_string.

Parameters:

• l (bounded_string) – Left string
• r (string) – Right string

Returns:

String with l and r concatenated.

strings_bounded."&" (l : string; r : bounded_string) → bounded_string

Concatenate a bounded_string to a string.

Parameters:

• l (string) – Left string
• r (bounded_string) – Right string

Returns:

String with l and r concatenated.

strings_bounded."&" (l : bounded_string; r : character) → bounded_string

Concatenate a character to a string.

Parameters:

• l (bounded_string) – Left string
• r (character) – Right character

Returns:

String with l and r concatenated.

strings_bounded."&" (l : character; r : bounded_string) → bounded_string

Concatenate a string to a character.

Parameters:

• l (character) – Left character
• r (bounded_string) – Right string

Returns:

String with l and r concatenated.

strings_bounded.element (source : bounded_string; index : positive) → character

Return the character at the index position.

Parameters:

• source (bounded_string) – String to index into
• index (positive) – Position of the character in the string

Returns:

Character at the index position.

strings_bounded.replace_element (source : inout bounded_string; index : in positive; by : in character)

Replace the character at the index position.

Parameters:

• source (inout bounded_string) – String to have element replaced
• index (in positive) – Index position to insert new character
• by (in character) – Character to place in the string

strings_bounded.slice (source : bounded_string; low : positive; high : natural) → string

Return a sliced range of a bounded_string.

Parameters:

• source (bounded_string) – String to slice
• low (positive) – low index of slice (inclusive)
• high (natural) – high index of slice (inclusive)

Returns:

Substring of source from low to high.

strings_bounded."=" (l : bounded_string; r : bounded_string) → boolean

Test two bounded strings for equality.

Parameters:

• l (bounded_string) – First string to compare
• r (bounded_string) – Second string to compare

Returns:

true when l and r are equal.

strings_bounded."=" (l : bounded_string; r : string) → boolean

Test a bounded_string and plain string for equality.

Parameters:

• l (bounded_string) – First string to compare
• r (string) – Second string to compare

Returns:

true when l and r are equal.

strings_bounded."=" (l : string; r : bounded_string) → boolean

Test a plain string and a bounded_string for equality.

Parameters:

• l (string) – First string to compare
• r (bounded_string) – Second string to compare

Returns:

true when l and r are equal.

strings_bounded."<" (l : bounded_string; r : bounded_string) → boolean

Test two bounded_strings for one lexicographically before the other.

Parameters:

• l (bounded_string) – First string to compare
• r (bounded_string) – Second string to compare

Returns:

true when l lexicographically proceeds r.

strings_bounded."<" (l : bounded_string; r : string) → boolean

Test a bounded_string and a plain string for one lexicographically before the other.

Parameters:

• l (bounded_string) – First string to compare
• r (string) – Second string to compare

Returns:

true when l lexicographically proceeds r.

strings_bounded."<" (l : string; r : bounded_string) → boolean

Test a plain string and a bounded_string for one lexicographically before the other.

Parameters:

• l (string) – First string to compare
• r (bounded_string) – Second string to compare

Returns:

true when l lexicographically proceeds r.

strings_bounded."<=" (l : bounded_string; r : bounded_string) → boolean

Test two bounded_strings for equality or one lexicographically before the other.

Parameters:

• l (bounded_string) – First string to compare
• r (bounded_string) – Second string to compare

Returns:

true when l and r are equal or l lexicographically proceeds r.

strings_bounded."<=" (l : bounded_string; r : string) → boolean

Test a bounded_string and a plain string for equality or one lexicographically before the other.

Parameters:

• l (bounded_string) – First string to compare
• r (string) – Second string to compare

Returns:

true when l and r are equal or l lexicographically proceeds r.

strings_bounded."<=" (l : string; r : bounded_string) → boolean

Test a plain string and a bounded_string for equality or one lexicographically before the other.

Parameters:

• l (string) – First string to compare
• r (bounded_string) – Second string to compare

Returns:

true when l and r are equal or l lexicographically proceeds r.

strings_bounded.">" (l : bounded_string; r : bounded_string) → boolean

Test two bounded_strings for one lexicographically after the other.

Parameters:

• l (bounded_string) – First string to compare
• r (bounded_string) – Second string to compare

Returns:

true when l lexicographically follows r.

strings_bounded.">" (l : bounded_string; r : string) → boolean

Test a bounded_string and a plain string for one lexicographically after the other.

Parameters:

• l (bounded_string) – First string to compare
• r (string) – Second string to compare

Returns:

true when l lexicographically follows r.

strings_bounded.">" (l : string; r : bounded_string) → boolean

Test a plain string and a bounded_string for one lexicographically after the other.

Parameters:

• l (string) – First string to compare
• r (bounded_string) – Second string to compare

Returns:

true when l lexicographically follows r.

strings_bounded.">=" (l : bounded_string; r : bounded_string) → boolean

Test two bounded_strings for equality or one lexicographically after the other.

Parameters:

• l (bounded_string) – First string to compare
• r (bounded_string) – Second string to compare

Returns:

true when l and r are equal or l lexicographically follows r.

strings_bounded.">=" (l : bounded_string; r : string) → boolean

Test a bounded_string and a plain string for equality or one lexicographically after the other.

Parameters:

• l (bounded_string) – First string to compare
• r (string) – Second string to compare

Returns:

true when l and r are equal or l lexicographically follows r.

strings_bounded.">=" (l : string; r : bounded_string) → boolean

Test a plain string and a bounded_string for equality or one lexicographically after the other.

Parameters:

• l (string) – First string to compare
• r (bounded_string) – Second string to compare

Returns:

true when l and r are equal or l lexicographically follows r.

strings_bounded.index (source : bounded_string; pattern : string; going : direction := forward; mapping : character_mapping := IDENTITY) → natural

Find the index of the first occurance of pattern in source from the beginning or end.

Parameters:

• source (bounded_string) – String to index into
• pattern (string) – Pattern to search for
• going (direction) – Search direction
• mapping (character_mapping) – Optional character mapping applied before the search

Returns:

Index position of pattern or 0 if not found.

strings_bounded.index (source : bounded_string; set : character_set; test : membership := inside; going : direction := forward) → natural

Find the index of first occurance of a character from set in source.

Parameters:

• source (bounded_string) – String to search
• set (character_set) – Character set to search for
• test (membership) – Check for characters inside or outside the set
• going (direction) – Search direction

Returns:

Index position of first matching character or 0 if not found.

strings_bounded.index_non_blank (source : bounded_string; going : direction := forward) → natural

Find the index of the first non-space character in source.

Parameters:

• source (bounded_string) – String to search
• going (direction) – Search direction

Returns:

Index position of first non-space character or 0 if none found.

strings_bounded.count (source : bounded_string; pattern : string; mapping : character_mapping := IDENTITY) → natural

Count the occurrences of pattern in source.

Parameters:

• source (bounded_string) – String to count patterns in
• pattern (string) – Pattern to count in source string

Returns:

Number or times pattern occurs in the source string.

strings_bounded.count (source : bounded_string; set : character_set) → natural

Count the occurrences of characters from set in source.

Parameters:

• source (bounded_string) – String to count characters in
• set (character_set) – Character set to count

Returns:

Number of times a character from set occurs in the source string.

strings_bounded.find_token (source : in bounded_string; set : in character_set; test : in membership; first : out positive; last : out natural)

Return the indices of a slice of source that satisfies the membership selection for the character set.

Parameters:

• source (in bounded_string) – String to search for the token
• set (in character_set) – Character set for the token
• test (in membership) – Check for characters inside or outside the set
• first (out positive) – Start index of the token
• last (out natural) – End index of the token or 0 if not found

strings_bounded.translate (source : bounded_string; mapping : character_mapping) → bounded_string

Convert a source string with the provided character mapping.

Parameters:

• source (bounded_string) – String to translate
• mapping (character_mapping) – Mapping to apply

Returns:

New string with applied mapping.

strings_bounded.translate (source : inout bounded_string; mapping : in character_mapping)

Convert a source string with the provided character mapping.

Parameters:

• source (inout bounded_string) – String to translate
• mapping (in character_mapping) – Mapping to apply

strings_bounded.replace_slice (source : bounded_string; low : positive; high : natural; by : string; drop : truncation := error) → bounded_string

Replace a slice of the source string with the contents of by.

Parameters:

• source (bounded_string) – String to replace
• low (positive) – Start of the slice (inclusive)
• high (natural) – End of the slice (inclusive)
• by (string) – String to insert into slice position

Returns:

New string with replaced slice.

strings_bounded.replace_slice (source : inout bounded_string; low : in positive; high : in natural; by : in string; drop : in truncation := error)

Replace a slice of the source string with the contents of by.

Parameters:

• source (inout bounded_string) – String to replace
• low (in positive) – Start of the slice (inclusive)
• high (in natural) – End of the slice (inclusive)
• by (in string) – String to insert into slice position
• drop (in truncation) – Truncation mode
• justify – Alignment mode
• pad – Padding character when result is shorter than original string

strings_bounded.insert (source : bounded_string; before : positive; new_item : string; drop : truncation := error) → bounded_string

Insert the string new_item before the selected index in source.

Parameters:

• source (bounded_string) – String to insert into
• before (positive) – Index position for insertion
• new_item (string) – String to insert

Returns:

Source string with new_item inserted.

strings_bounded.insert (source : inout bounded_string; before : in positive; new_item : in string; drop : in truncation := error)

Insert the string new_item before the selected index in source.

Parameters:

• source (inout bounded_string) – String to insert into
• before (in positive) – Index position for insertion
• new_item (in string) – String to insert
• drop (in truncation) – Truncation mode

strings_bounded.overwrite (source : bounded_string; position : positive; new_item : string; drop : truncation := error) → bounded_string

Overwrite new_item into source starting at the selected position.

Parameters:

• source (bounded_string) – String to overwrite
• position (positive) – Index position for overwrite
• new_item (string) – String to write into source

Returns:

New string with overwritten item.

strings_bounded.overwrite (source : inout bounded_string; position : in positive; new_item : in string; drop : in truncation := error)

Overwrite new_item into source starting at the selected position.

Parameters:

• source (inout bounded_string) – String to overwrite
• position (in positive) – Index position for overwrite
• new_item (in string) – String to write into source
• drop (in truncation) – Truncation mode

strings_bounded.delete (source : bounded_string; from : positive; through : natural) → bounded_string

Delete a slice from source. If from is greater than through, source is unmodified.

Parameters:

• source (bounded_string) – String to delete a slice from
• from (positive) – Start index (inclusive)
• through (natural) – End index (inclusive)

Returns:

New string with a slice deleted.

strings_bounded.delete (source : inout bounded_string; from : in positive; through : in natural)

Delete a slice from source. If from is greater than through, source is unmodified.

Parameters:

• source (inout bounded_string) – String to delete a slice from
• from (in positive) – Start index (inclusive)
• through (in natural) – End index (inclusive)
• justify – Position of shortened result in string
• pad – Character to use as padding for shortened string

strings_bounded.trim (source : bounded_string; side : trim_end) → bounded_string

Remove space characters from leading, trailing, or both ends of source.

Parameters:

• source (bounded_string) – String to trim
• side (trim_end) – Which end to trim

Returns:

Source string with space trimmed.

strings_bounded.trim (source : inout bounded_string; side : in trim_end)

Remove space characters from leading, trailing, or both ends of source.

Parameters:

• source (inout bounded_string) – String to trim
• side (in trim_end) – Which end to trim

strings_bounded.trim (source : bounded_string; left : character_set; right : character_set) → bounded_string

Remove all leading characters in left and trailing characters in right from source.

Parameters:

• source (bounded_string) – String to trim
• left (character_set) – Index position for start trim
• right (character_set) – Index position for end trim

Returns:

Source string with ends trimmed.

strings_bounded.trim (source : inout bounded_string; left : in character_set; right : in character_set)

Remove all leading characters in left and trailing characters in right from source.

Parameters:

• source (inout bounded_string) – String to trim
• left (in character_set) – Index position for start trim
• right (in character_set) – Index position for end trim

strings_bounded.head (source : bounded_string; count : natural; pad : character := ' '; drop : truncation := error) → bounded_string

Return the first count characters from source.

Parameters:

• source (bounded_string) – String to slice from
• count (natural) – Number of characters to take from the start of source
• pad (character) – Characters to pad with if source length is less than count
• drop (truncation) – Truncation behavior

Returns:

A string of length count.

strings_bounded.head (source : inout bounded_string; count : in natural; pad : in character := ' '; drop : in truncation := error)

Return the first count characters from source.

Parameters:

• source (inout bounded_string) – String to slice from
• count (in natural) – Number of characters to take from the start of source
• pad (in character) – Characters to pad with if source length is less than count
• drop (in truncation) – Truncation behavior

strings_bounded.tail (source : bounded_string; count : natural; pad : character := ' '; drop : truncation := error) → bounded_string

Return the last count characters from source.

Parameters:

• source (bounded_string) – String to slice from
• count (natural) – Number of characters to take from the end of source
• pad (character) – Characters to pad with if source length is less than count
• drop (truncation) – Truncation behavior

Returns:

A string of length count.

strings_bounded.tail (source : inout bounded_string; count : in natural; pad : in character := ' '; drop : in truncation := error)

Return the last count characters from source.

Parameters:

• source (inout bounded_string) – String to slice from
• count (in natural) – Number of characters to take from the end of source
• pad (in character) – Characters to pad with if source length is less than count
• drop (in truncation) – Truncation behavior

strings_bounded."*" (l : natural; r : character) → bounded_string

Replicate a character left number of times.

Parameters:

• left – Number of times to repeat the right operand
• right – Character to repeat in string

Returns:

String with repeated character.

strings_bounded."*" (l : natural; r : string) → bounded_string

Replicate a string left number of times.

Parameters:

• left – Number of times to repeat the right operand
• right – String to repeat in result string

Returns:

String with repeated substring.

strings_bounded."*" (l : natural; r : bounded_string) → bounded_string

Replicate a bounded_string left number of times.

Parameters:

• left – Number of times to repeat the right operand
• right – String to repeat in result string

Returns:

String with repeated substring.

strings_bounded.replicate (count : natural; item : character; drop : truncation := error) → bounded_string

Replicate a character count number of times.

Parameters:

• count (natural) – Number of times to repeat the item operand
• item (character) – Character to repeat in string
• drop (truncation) – Truncation behavior

Returns:

String with repeated character.

strings_bounded.replicate (count : natural; item : string; drop : truncation := error) → bounded_string

Replicate a string count number of times.

Parameters:

• count (natural) – Number of times to repeat the item operand
• item (string) – String to repeat in result string
• drop (truncation) – Truncation behavior

Returns:

String with repeated substring.

strings_bounded.replicate (count : natural; item : bounded_string; drop : truncation := error) → bounded_string

Replicate a bounded_string count number of times.

Parameters:

• count (natural) – Number of times to repeat the item operand
• item (bounded_string) – String to repeat in result string
• drop (truncation) – Truncation behavior

Returns:

String with repeated substring.