string library

The string: library contains primitives for string manipulation, most of which are inherited from Java.

In Ripple, strings are RDF literals which may be either typed or untyped. For example, "foo" represents a plain literal, while "foo"^^xsd:string represents a string-typed literal. Both string-typed and plain literals are consumed and produced by string: primitives. As arguments, string-typed and plain literals are interchangeable. However, values produced by string: primitives obey the following rule: if all of the string arguments to the primitive are plain literals, then the produced value is also a plain literal. If any arguments are string-typed literals, then the produced value is also a string-typed literal.

Custom primitives

There are a few string primitives in Ripple which are not directly based on Java.

md5

This primitive finds the MD5 hash of a string.

Example:

1)  "a very long string" md5.

  [1]  "6009a2eec5261aaafae1b20245fc4d65"

percent-decoded

This primitive converts a (per RFC 3986) percent-encoded string to an unencoded string using the UTF-8 character set.

Example:

1)  "the%20Answer" percent-decoded.

  [1]  "the Answer"

percent-encoded

This primitive percent-encodes a string per RFC 3986 using the UTF-8 character set.

Example:

1)  "http://example.org/searchFor?query=" "the answer" percent-encoded. concat.

  [1]  "http://example.org/searchFor?query=the%20answer"

sha1

This primitive finds the SHA-1 hash of a string.

Example:

1)  <mailto:josh@fortytwo.net> to-string. sha1.

  [1]  "1f62decdebec6594187ed1fa02355d9db33184fa"^^xsd:string

Java String primitives

The behavior of these primitives is inherited from analogous methods of Java's String class. Each primitive consumes one more argument than the corresponding Java method, in which the first (deepest) argument is analogous to the this object of a Java method call. The remaining arguments (if any) are specified in the same order as those of the method. Since Ripple is not a polymorphic language, at most one of each set of overloaded Java methods (e.g. [String.indexOf](http://download.oracle.com/javase/6/docs/api/java/lang/String.html#indexOf(int, int)), of which there are three variants) is supported. The order of arguments on the stack is identical to the order of arguments to the corresponding method, where the first (deepest) argument is the reference object. All primitives produce exactly one solution per valid input stack.

concat

This primitive concatenates two strings. It is analogous to Java's [String.concat(String)](http://download.oracle.com/javase/6/docs/api/java/lang/String.html#concat(java.lang.String\)) method.

Example:

1)  "con" "cat" concat.

  [1]  "concat"

contains

This primitive produces true if a given string contains another given string as a substring, otherwise false. It is analogous to Java's [String.contains(CharSequence)](http://download.oracle.com/javase/6/docs/api/java/lang/String.html#contains(java.lang.CharSequence\)) method.

Examples:

1)  "Mississippi" "sip" contains.

  [1]  true

2)  "Mississippi" "gulp" contains.

  [1]  false

ends-with

This primitive produces true if a given string ends with a given string suffix, otherwise false. It is analogous to Java's [String.endsWith(String)](http://download.oracle.com/javase/6/docs/api/java/lang/String.html#endsWith(java.lang.String\)) method.

Examples:

1)  "Mississippi" "pi" ends-with.

  [1]  true

2)  "Mississippi" "delta" ends-with.

  [1]  false

3)  "Mississippi" "" ends-with.     

  [1]  true

index-of

This primitive produces the index of the first occurrence in a given string of a given substring, where strings are zero-indexed. It is analogous to Java's [String.indexOf(String)](http://download.oracle.com/javase/6/docs/api/java/lang/String.html#indexOf(java.lang.String\)) method. If the substring does not occur, this primitive produces a value of -1.

Example:

1)  "Mississippi" "is" index-of.

  [1]  1

last-index-of

This primitive produces the index of the last occurrence in a given string of a given substring, where strings are zero-indexed. It is analogous to Java's [String.lastIndexOf(String)](http://download.oracle.com/javase/6/docs/api/java/lang/String.html#lastIndexOf(java.lang.String\)) method. If the substring does not occur, this primitive produces a value of -1.

Example:

1)  "Mississippi" "is" last-index-of.

  [1]  4

length

This primitive produces the length (number of characters in) a string. It is analogous to Java's [String.length()](http://download.oracle.com/javase/6/docs/api/java/lang/String.html#length(\)) method.

Example:

1)  "the coast of Britain" length.

  [1]  20

matches

This primitive produces true if a given string matches a given regular expression, otherwise false. It is analogous to Java's [String.matches(String)](http://download.oracle.com/javase/6/docs/api/java/lang/String.html#matches(java.lang.String\)) method.

Examples:

1)  "shhhhh" "sh*" matches.

  [1]  true

2)  "shhhhh" "(sh)*" matches.

  [1]  false

replace-all

This primitive replaces all occurrences, in a given string, of a given regular expression. It is analogous to Java's [String.replaceAll(String, String)](http://download.oracle.com/javase/6/docs/api/java/lang/String.html#replaceAll(java.lang.String, java.lang.String)) method.

Example:

1)  "Our net earnings in 2010 were $42." "[0-9]+" "___" replace-all.

  [1]  "Our net earnings in ___ were $___."

split

This primitive splits a given string around matches of a given regular expression, producing a list of strings. It is analogous to Java's [String.split(String)](http://download.oracle.com/javase/6/docs/api/java/lang/String.html#split(java.lang.String\)) method.

Example:

1)  "one two three four five" " " split.

  [1]  ("one" "two" "three" "four" "five")

starts-with

This primitive produces true if a given string starts with a given prefix, otherwise false. It is analogous to Java's [String.startsWith(String)](http://download.oracle.com/javase/6/docs/api/java/lang/String.html#startsWith(java.lang.String\)) method.

Example:

1)  "sing a song of sixpence" " " split. ("s" starts-with.) map.

  [1]  (true false true false true)

substring

This primitive produces the substring of a given string between a given start index (inclusive) and end index (exclusive), where strings are zero-indexed. It is analogous to Java's [String.substring(int, int)](http://download.oracle.com/javase/6/docs/api/java/lang/String.html#substring(int, int)) method.

Example:

1)  "life" 1 3 substring.

  [1]  "if"

to-lower-case

This primitive converts a given string to lower case. It is analogous to Java's [String.toLowerCase()](http://download.oracle.com/javase/6/docs/api/java/lang/String.html#toLowerCase(\)) method.

Example:

1)  "Zaphod Beeblebrox" to-lower-case.

  [1]  "zaphod beeblebrox"

to-upper-case

This primitive converts a given string to upper case. It is analogous to Java's [String.toUpperCase()](http://download.oracle.com/javase/6/docs/api/java/lang/String.html#toUpperCase(\)) method.

Example:

1)  "Don't panic!" to-upper-case.

  [1]  "DON'T PANIC!"

trim

This primitive trims the leading and trailing white space off of a given string. It is analogous to Java's [String.trim()](http://download.oracle.com/javase/6/docs/api/java/lang/String.html#trim(\)) method.

Example:

1)  "  foo " trim. 

  [1]  "foo"