Skip to content

Latest commit

 

History

History
892 lines (443 loc) · 20.3 KB

README.md

File metadata and controls

892 lines (443 loc) · 20.3 KB
Raw

String Functions

CMake has one utility for working with string: string(). Inside of the jewel there is hidden lots of functionality which just has to be exposed correctly to the user. I also wanted to expose this functionality in the cmakepp way of doing things (ie return values)

So I have created somewhat alot of functions which does things that you might need and alot of what you will probably never need - but feel good about because its there :)

Function List

Function Descriptions

ascii_char

ascii_code

ascii_generate_table

generates the ascii table and stores it in the global ascii_table variable

cmake_string_to_json

delimiters

delimiters()->[delimiter_begin, delimiter_end]

parses delimiters and retruns a list of length 2 containing the specified delimiters. The usefullness of this function becomes apparent when you use string_take_delimited

argument_escape

format

format(<template string>)-><string>

this function utilizes assign(...) to evaluate expressions which are enclosed in handlebars: { }

Examples

# create a object
obj("{a:1,b:[2,3,4,5,6],c:{d:3}}")
ans(data)
## use format to print navigated expressiosn:
format("{data.a} + {data.c.d} = {data.b[2]}") => "1 + 3 = 4"
format("some numbers: {data.b[2:$]}") =>  "some numbers: 4;5;6"
...

Note: You may not use ASCII-29 since it is used interally in this function. If you don't know what this means - don't worry

regex_search

string_append_line_indented

string_char_at

(<input:<string>> <index:<int>>)-><string>

Returns the character at the specified position (index). Indexing of strings starts at 0. Indices less than -1 are translated into "length - |index|"

Examples set(input "example") string_char_at("${input}" 3) # => "m" string_char_at("${input}"-3) # => "l"

string_char_at_set

(<input:<string>> <index:<int>> <char:<string>>)-><string>

Sets the character at the specified position (index) to the input 'char'. Indexing of strings starts at 0. Indices less than -1 are translated into "length - |index|"

Examples set(input "example") string_char_at_set("${input}" 0 "E") # => "Example" string_char_at_set("${input}" 2 "A") # => "exAmple" string_char_at_set("${input}" -2 "E") # => "examplE"

string_codes

string_combine

combines the varargs into a string joining them with separator e.g. string_combine(, a b c) => "a,b,c"

string_concat

string_contains

(<str:<string>> <search:<string>>)-><bool>

Returns true if the input string "str" contains "search"

Examples set(input "endswith") string_contains("${input}" "with") # => true string_contains("${input}" "swi") # => true

string_decode_delimited

tries to parse a delimited string returns either the original or the parsed delimited string delimiters can be specified via varargs see also string_take_delimited

string_ends_with

(<str:<string>> <search:<string>>)-><bool>

Returns true if the input string "str" ends with "search"

Examples set(input "endswith") string_ends_with("${input}" "with") # => true string_ends_with("${input}" "width") # => false

string_eval

evaluates the string in the current scope this is done by macro variable expansion evaluates both ${} and @ style variables

string_find

(<str:<string>> <substr:<string>>)-><int>

Returns the position where the "substr" was found in the input "str", otherwise -1. NOTE: The flag REVERSE causes the last position of "substr" to be returned

Examples set(input "endswith") string_find("${input}" "with") # => 4 string_find("${input}" "swi") # => 3

string_isempty

(<str:<string>>)-><bool>

Returns true if the input string "str" is empty Note: cmake evals "false", "no" which destroys tests for real emtpiness

Examples set(input "") string_isempty("${input}") # => true set(input "false") string_isempty("${input}") # => false

string_isnumeric

(<str:<string>>)-><bool>

Returns true if the input string "str" is a positive integer including "0"

Examples set(input "1") string_isnumeric("${input}") # => true set(input "-1") string_isnumeric("${input}") # => false

string_length

(<str:<string>>)-><int>

Returns the length of the input string "str"

Examples set(input "a") string_length("${input}") # => 1 set(input "ab c") string_length("${input}") # => 4

string_lines

(<input:<string>>)-><string...>

Splits the specified string "input" into lines Caveat: The string would have to be semicolon encoded to correctly display lines with semicolons

Examples set(input "a\nb") string_lines("${input}") # => "a;b" set(input "a b\nc") string_lines("${input}") # => "a b;c"

string_match

(<input:<string>>)-><bool>

Evaluates string "str" against regex "regex". Returns true if it matches.

Examples set(input "a?") string_match("${input}" "[a-z]+\?") # => true set(input "a bc .") string_match("${input}" "^b") # => false

string_normalize

(<input:<string>>)-><string>

Replaces all non-alphanumerical characters in the string "input" with an underscore

Examples set(input "a?") string_normalize("${input}") # => "a_" set(input "a bc .") string_normalize("${input}") # => "a bc _"

string_normalize_index

(<str:<string>> <index:<int>>)-><int>

Normalizes the index "index" of a corresponding input string "str". Negative indices are transformed into positive values: length - |index| Returns -1 if index is out of bounds (index > length of string or length - |index| + 1 < 0)

Examples set(input "abcd") string_normalize_index("${input}" 3) # => 3 string_normalize_index("${input}" -2) # => 3

string_overlap

(<lhs:<string>> <rhs:<string>>)-><string>

Returns the overlapping part of input strings "lhs" and "rhs". Starts at first char and continues until chars don't match.

Examples set(input1 "abcd") set(input2 "abyx") string_overlap("${input1}" "${input2}") # => "ab" set(input2 "wxyz") string_overlap("${input1}" "${input2}") # => ""

string_pad

(<str:<string>> <len:<int>> <argn:<string>>)-><string>

Pads the specified string to be as long as specified length "len".

  • If the string is longer then nothing is padded
  • If no delimiter is specified than " " (space) is used
  • If "--prepend" is specified for "argn" the padding is inserted at the beginning of "str"

Examples set(input "word") string_pad("${input}" 6) # => "word " string_pad("${input}" 4) # => "word"

string_random

()-><string>

Returns a randomly generated string. TODO: implement

Examples string_random() # =>

string_regex_escape

(<str:<string>>)-><string>

Escapes chars used by regex strings in the input string "str". Escaped characters: "\ / ] [ * . - ^ $ ? ) ( |"

Examples set(input "()") string_regex_escape("${input}") # => "()" set(input "no_escape") string_regex_escape("${input}") # => "no_escape"

string_remove_beginning

(<original:<string>> <beginning:<string>>)-><string>

Removes the beginning "n"-chars of the string "original". Number of chars "n" is calculated based on string "beginning".

Examples set(input "abc") string_remove_ending("${input}" "a") # => "ab" string_remove_ending("${input}" "ab") # => "a"

string_remove_ending

(<original:<string>> <ending:<string>>)-><string>

Removes the back "n"-chars of the string "original". Number of chars "n" is calculated based on string "ending".

Examples set(input "abc") string_remove_ending("${input}" "a") # => "ab" string_remove_ending("${input}" "ab") # => "a"

string_repeat

(<what:<string>> <n:<int>>)-><string>

Repeats string "what" "n" times and separates them with an optional separator

Examples set(input "a") string_repeat("${input}" 2) # => "aa" string_repeat("${input}" 2 "@") # => "a@a"

string_replace

(<str:<string>> <pattern:<string>> <replace:<string>>)-><string>

Replaces all occurences of "pattern" with "replace" in the input string "str".

Examples set(input "abca") string_replace("a" "z" "${input}") # => "zbcz" set(input "aaa") string_replace("a" "z" "${input}") # => "zzz"

string_replace_first

(<string_input:<string>> <string_search:<string>> <string_replace:<string>>)-><string>

Replaces the first occurence of "string_search" with "string_replace" in the input string "string_input".

Examples set(input "abc") string_replace_first("${input}" "a" "z") # => "zbc" set(input "aac") string_replace_first("${input}" "aa" "z") # => "zc"

string_shorten

(<str:<string>> <max_length:<int>>)-><string>

Shortens the string "str" to be at most "max_length" characters long. Note on "max_length": max_length includes the shortener string (default 3 chars "..."). Returns the result in "res".

Examples set(input "abcde") string_shorten("${input}" 4) # => "a..." string_shorten("${input}" 3) # => "..." string_shorten("${input}" 2) # => "" string_shorten("${input}" 2 ".") # => "a."

string_slice

(<str:<string>> <start_index:<int>> <end_index:<int>>)-><string>

Extracts a portion from string "str" at the specified index: [start_index, end_index) Indexing of slices starts at 0. Indices less than -1 are translated into "length - |index|" Returns the result in "result".

Examples set(input "abc") string_slice("${input}" 0 1) # => "a" set(input "abc") string_slice("${input}" 0 2) # => "ab"

string_split

(<string_subject:<string>> <split_regex:<string>>)-><string...>

Splits the string "input" at the occurence of the regex "split_regex". Returns the result in "res". TODO: does not handle strings containing list separators properly

Examples set(input "a@b@c") string_split("${input}" "@") # => "a;b;c"

string_split_at_first

(<parta:<string&>> <partb:<string&>> <input:<string>> <separator:<string>>)-><parta:<string&>> <partb:<string&>>

Splits the string "input" at the first occurence of "separator" and returns both parts in the string references "parta" and "partb". See Examples for passing references.

Examples set(input "a@b@c") string_split_at_first(partA partB "${input}" "@") # => partA equals "a", partB equals "b@c"

string_split_at_last

(<parta:<string&>> <partb:<string&>> <input:<string>> <separator:<string>>)-><parta:<string&>> <partb:<string&>>

Splits the string "input" at the last occurence of "separator" and returns both parts in the string references "parta" and "partb". See Examples for passing references.

Examples set(input "a@b@c") string_split_at_last(partA partB "${input}" "@") # => partA equals "a@b", partB equals "c"

string_split_parts

(<str:<string>> <length:<int>>)-><first_node:<linked list>>

Splits the string "str" into multiple parts of length "length". Returns a linked list of the parts

Examples set(input "abc") string_split_parts("${input}" 1) # => linked_list("a", "b", "c") string_split_parts("${input}" 2) # => linked_list("ab", "c") string_split_parts("${input}" 3) # => linked_list("abc")

string_starts_with

(<str:<string>> <search:<string>>)-><bool>

Returns true if "str" starts with the string "search"

Examples string_starts_with("substring" "sub") # => true string_starts_with("substring" "ub") # => false

string_substring

(<str:<string>> <start:<int>> <end:<int>>)-><string>

Wrapper function for substring. Returns a substring of input "str" with the index parameter "start" and optionally "len". Note on indexing: len is the amount of chars to be extracted starting from index "start"

Examples string_substring("substring" 1) # => "ubstring" string_substring("substring" 1 2) # => "ub" string_substring("substring" -3 2) # => "ng"

string_take

(<str_name:<string&>> <match:<string>>)-><str_name:<string&>> string>

Removes "match" from a string reference "str_name" and returns the "match" string. Only matches from the beginning of the string reference.

Examples set(input "word") string_take(input "w") # => input equals "ord", match equals "w" set(input "word") string_take(input "ord") # => input is unchanged, no match is returned

string_take_address

(<str_ref:<string&>>)-><str_ref:<string&>> <string>

Removes an address (regex format: "�:[1-9][0-9]*") from a string reference and returns the address in "res". The address is also removed from the input string reference (str_ref).

Examples

string_take_any_delimited

(<str_ref:<string&>> <delimiters:<delimiter:<string>>...>>)-><str_ref:<string&>> <string>

Removes delimiters of a string and the undelimited string is returned. The undelimited string is also removed from the input string reference (__str_ref). Notes on the delimiter:

  • Can be a list of delimiters
  • Beginning and end delimiter can be specified
  • May only be a single char
  • Escaped delimiters are unescaped

Examples set(in_ref_str "'a string'") string_take_any_delimited(in_ref_str ') # => in_ref_str equals "" and match equals "a string" set(in_ref_str ""a string", ") string_take_any_delimited(in_ref_str "'', <>") # => in_ref_str equals ""a string"" and match equals "another one"

string_take_delimited

(<__str_ref:<string&>>)-><__str_ref:<string&>> <string>

Removes delimiters of a string and the undelimited string is returned. The undelimited string is also removed from the input string reference (__str_ref). Notes on the delimiter:

  • Default is double quote ""
  • Beginning and end delimiter can be specified
  • May only be a single char
  • Escaped delimiters are unescaped

Examples set(in_ref_str "'a string'") string_take_delimited(in_ref_str ') # => in_ref_str equals "" and res equals "a string" set(in_ref_str "'a string'") string_take_delimited(in_ref_str "''") # => same as above

string_take_regex

(<str_name:<string&>> <regex:<string>> <replace:<string>>)-><str_name:<string&>> <string>

Tries to match the regex at the begging of ${${str_name}} and returns the match. Side effect: Input reference ${str_name} is shortened in the process. See Examples for passing references.

Examples set(in_ref_str "keep_two_whitespaces ") string_take_regex(in_ref_str "[^ ]*" "") # => in_ref_str equals " "

string_take_whitespace

(<__str_ref:<string&>>)-><__str_ref:<string&>>

Removes preceeding whitespaces of the input string reference. See Examples for passing references.

Examples set(in_ref_str " test") string_take_whitespace(in_ref_str) # => in_ref_str equals "test" set(in_ref_str " test ") string_take_whitespace(in_ref_str) # => in_ref_str equals "test "

string_tolower

(<input:<string>>)-><string>

Transforms the specified string to lower case.

Examples string_tolower("UPPER") # => "upper"

string_toupper

(<input:<string>>)-><string>

Transforms the specified string to upper case.

Examples string_tolower("lower") # => "LOWER"

string_to_title

(<input:<string>>)-><string>

Transforms the input string to title case. Tries to be smart and keeps some words small. List of words that are kept small: "a, an, and, as, at, but, by, en, for, if, in, of, on, or, the, to, via, vs, v, v., vs."

Examples set(input "the function string_totitle works") string_to_title("${input}") # => "The Function string_totitle Works" set(input "testing a small word") string_to_title("${input}") # => "Testing a Small Word"

string_trim

(<input:<string>>)-><string>

Trims the string, by removing whitespaces at the beginning and end.

Examples string_tolower(" whitespaces ") # => "whitespaces"

string_trim_to_difference

(<lhs:<string&>> <rhs:<string&>>)-><lhs:<string&>> <rhs:<string&>>

Removes the beginning of the string that matches from reference string "lhs" and "rhs". See Examples for passing references.

Examples set(in_lhs "simple test") set(in_rhs "simple a") string_trim_to_difference(in_lhs in_rhs) # => in_lhs equals "test", in_rhs equals "a" set(in_lhs "a test") set(in_rhs "b test") string_trim_to_difference(in_lhs in_rhs) # => in_lhs equals "a test", in_rhs equals "b test"