Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
String(3)			   OCamldoc			     String(3)

NAME
       String -	String operations.

Module
       Module	String

Documentation
       Module String
	: sig end

       String operations.

       A  string  is  an immutable data	structure that contains	a fixed-length
       sequence	of (single-byte) characters. Each character can	be accessed in
       constant	time through its index.

       Given  a	 string	s of length l ,	we can access each of the l characters
       of s via	its index in the sequence. Indexes start at 0 ,	 and  we  will
       call an index valid in s	if it falls within the range [0...l-1] (inclu-
       sive). A	position is the	point between two characters or	at the	begin-
       ning  or	 end of	the string.  We	call a position	valid in s if it falls
       within the range	[0...l]	(inclusive). Note that the character at	 index
       n is between positions n	and n+1	.

       Two parameters start and	len are	said to	designate a valid substring of
       s if len	>= 0 and start and start+len are valid positions in s .

       OCaml strings used to be	modifiable in  place,  for  instance  via  the
       String.set  and	String.blit  functions	described below. This usage is
       deprecated  and	only  possible	when  the  compiler  is	 put  in  "un-
       safe-string"  mode  by  giving  the  -unsafe-string command-line	option
       (which is currently the default for reasons of backward compatibility).
       This  is	 done by making	the types string and bytes (see	module Bytes )
       interchangeable so that functions expecting byte	sequences can also ac-
       cept strings as arguments and modify them.

       All  new	 code  should  avoid  this  feature  and  be compiled with the
       -safe-string command-line option	to enforce the separation between  the
       types string and	bytes .

       val length : string -> int

       Return the length (number of characters)	of the given string.

       val get : string	-> int -> char

       String.get  s n returns the character at	index n	in string s .  You can
       also write s.[n]	instead	of String.get s	n .

       Raise Invalid_argument if n not a valid index in	s .

       val set : bytes -> int -> char -> unit

       Deprecated.  This is a deprecated alias of Bytes.set .

       String.set s n c	modifies byte sequence s in place, replacing the  byte
       at  index  n  with  c  .	  You  can  also  write	 s.[n] <- c instead of
       String.set s n c	.

       Raise Invalid_argument if n is not a valid index	in s .

       val create : int	-> bytes

       Deprecated.  This is a deprecated alias of Bytes.create .

       String.create n returns a fresh byte sequence of	length n  .   The  se-
       quence is uninitialized and contains arbitrary bytes.

       Raise Invalid_argument if n < 0 or n > Sys.max_string_length .

       val make	: int -> char -> string

       String.make  n  c  returns a fresh string of length n , filled with the
       character c .

       Raise Invalid_argument if n < 0 or n > Sys.max_string_length .

       val init	: int -> (int -> char) -> string

       String.init n f returns a string	of length n , with  character  i  ini-
       tialized	to the result of f i (called in	increasing index order).

       Raise Invalid_argument if n < 0 or n > Sys.max_string_length .

       Since 4.02.0

       val copy	: string -> string

       Deprecated.   Because strings are immutable, it doesn't make much sense
       to make identical copies	of them.

       Return a	copy of	the given string.

       val sub : string	-> int -> int -> string

       String.sub s start len returns a	fresh string of	length len ,  contain-
       ing the substring of s that starts at position start and	has length len
       .

       Raise Invalid_argument if start and len do not designate	a  valid  sub-
       string of s .

       val fill	: bytes	-> int -> int -> char -> unit

       Deprecated.  This is a deprecated alias of Bytes.fill .

       String.fill  s start len	c modifies byte	sequence s in place, replacing
       len bytes with c	, starting at start .

       Raise Invalid_argument if start and len do not designate	a valid	 range
       of s .

       val blit	: string -> int	-> bytes -> int	-> int -> unit

       Same as Bytes.blit_string .

       val concat : string -> string list -> string

       String.concat  sep  sl  concatenates the	list of	strings	sl , inserting
       the separator string sep	between	each.

       Raise   Invalid_argument	   if	 the	result	  is	longer	  than
       Sys.max_string_length bytes.

       val iter	: (char	-> unit) -> string -> unit

       String.iter f s applies function	f in turn to all the characters	of s .
       It is equivalent	to f s.[0]; f s.[1]; ...; f s.[String.length s	-  1];
       () .

       val iteri : (int	-> char	-> unit) -> string -> unit

       Same  as	 String.iter , but the function	is applied to the index	of the
       element as first	argument (counting from	0), and	the  character	itself
       as second argument.

       Since 4.00.0

       val map : (char -> char)	-> string -> string

       String.map  f  s	 applies function f in turn to all the characters of s
       (in increasing index order) and stores the results in a new string that
       is returned.

       Since 4.00.0

       val mapi	: (int -> char -> char)	-> string -> string

       String.mapi  f s	calls f	with each character of s and its index (in in-
       creasing	index order) and stores	the results in a new  string  that  is
       returned.

       Since 4.02.0

       val trim	: string -> string

       Return a	copy of	the argument, without leading and trailing whitespace.
       The characters regarded as whitespace are: ' ' ,	'\012' , '\n' ,	'\r' ,
       and '\t'	.  If there is neither leading nor trailing whitespace charac-
       ter in the argument, return the original	string itself, not a copy.

       Since 4.00.0

       val escaped : string -> string

       Return a	copy of	the argument, with special characters  represented  by
       escape  sequences,  following  the  lexical  conventions	of OCaml.  All
       characters outside the ASCII printable range (32..126) are escaped,  as
       well as backslash and double-quote.

       If  there  is no	special	character in the argument that needs escaping,
       return the original string itself, not a	copy.

       Raise   Invalid_argument	   if	 the	result	  is	longer	  than
       Sys.max_string_length bytes.

       The  function  Scanf.unescaped  is  a  left  inverse  of	escaped	, i.e.
       Scanf.unescaped (escaped	s) = s for  any	 string	 s  (unless  escape  s
       fails).

       val index : string -> char -> int

       String.index s c	returns	the index of the first occurrence of character
       c in string s .

       Raise Not_found if c does not occur in s	.

       val index_opt : string -> char -> int option

       String.index_opt	s c returns the	index of the first occurrence of char-
       acter c in string s , or	None if	c does not occur in s .

       Since 4.05

       val rindex : string -> char -> int

       String.rindex s c returns the index of the last occurrence of character
       c in string s .

       Raise Not_found if c does not occur in s	.

       val rindex_opt :	string -> char -> int option

       String.rindex_opt s c returns the index of the last occurrence of char-
       acter c in string s , or	None if	c does not occur in s .

       Since 4.05

       val index_from :	string -> int -> char -> int

       String.index_from  s  i	c returns the index of the first occurrence of
       character c in string s after position i	.  String.index	s c is equiva-
       lent to String.index_from s 0 c .

       Raise  Invalid_argument	if  i  is  not	a valid	position in s .	 Raise
       Not_found if c does not occur in	s after	position i .

       val index_from_opt : string -> int -> char -> int option

       String.index_from_opt s i c returns the index of	the  first  occurrence
       of character c in string	s after	position i or None if c	does not occur
       in s after position i .

       String.index_opt	s c is equivalent to String.index_from_opt  s  0  c  .
       Raise Invalid_argument if i is not a valid position in s	.

       Since 4.05

       val rindex_from : string	-> int -> char -> int

       String.rindex_from  s  i	 c returns the index of	the last occurrence of
       character c in string s before position i+1 .   String.rindex  s	 c  is
       equivalent to String.rindex_from	s (String.length s - 1)	c .

       Raise  Invalid_argument	if  i+1	 is not	a valid	position in s .	 Raise
       Not_found if c does not occur in	s before position i+1 .

       val rindex_from_opt : string -> int -> char -> int option

       String.rindex_from_opt s	i c returns the	index of the  last  occurrence
       of  character  c	 in string s before position i+1 or None if c does not
       occur in	s before position i+1 .

       String.rindex_opt  s  c	is  equivalent	to  String.rindex_from_opt   s
       (String.length s	- 1) c .

       Raise Invalid_argument if i+1 is	not a valid position in	s .

       Since 4.05

       val contains : string ->	char ->	bool

       String.contains s c tests if character c	appears	in the string s	.

       val contains_from : string -> int -> char -> bool

       String.contains_from  s start c tests if	character c appears in s after
       position	start .	 String.contains s  c  is  equivalent  to  String.con-
       tains_from s 0 c	.

       Raise Invalid_argument if start is not a	valid position in s .

       val rcontains_from : string -> int -> char -> bool

       String.rcontains_from s stop c tests if character c appears in s	before
       position	stop+1 .

       Raise Invalid_argument if stop <	0 or stop+1 is not a valid position in
       s .

       val uppercase : string -> string

       Deprecated.   Functions	operating  on Latin-1 character	set are	depre-
       cated.

       Return a	copy of	the argument, with all lowercase letters translated to
       uppercase, including accented letters of	the ISO	Latin-1	(8859-1) char-
       acter set.

       val lowercase : string -> string

       Deprecated.  Functions operating	on Latin-1 character  set  are	depre-
       cated.

       Return a	copy of	the argument, with all uppercase letters translated to
       lowercase, including accented letters of	the ISO	Latin-1	(8859-1) char-
       acter set.

       val capitalize :	string -> string

       Deprecated.   Functions	operating  on Latin-1 character	set are	depre-
       cated.

       Return a	copy of	the argument, with the first character set  to	upper-
       case, using the ISO Latin-1 (8859-1) character set..

       val uncapitalize	: string -> string

       Deprecated.   Functions	operating  on Latin-1 character	set are	depre-
       cated.

       Return a	copy of	the argument, with the first character set  to	lower-
       case, using the ISO Latin-1 (8859-1) character set..

       val uppercase_ascii : string -> string

       Return a	copy of	the argument, with all lowercase letters translated to
       uppercase, using	the US-ASCII character set.

       Since 4.03.0

       val lowercase_ascii : string -> string

       Return a	copy of	the argument, with all uppercase letters translated to
       lowercase, using	the US-ASCII character set.

       Since 4.03.0

       val capitalize_ascii : string ->	string

       Return  a  copy of the argument,	with the first character set to	upper-
       case, using the US-ASCII	character set.

       Since 4.03.0

       val uncapitalize_ascii :	string -> string

       Return a	copy of	the argument, with the first character set  to	lower-
       case, using the US-ASCII	character set.

       Since 4.03.0

       type t =	string

       An alias	for the	type of	strings.

       val compare : t -> t -> int

       The  comparison	function  for  strings,	with the same specification as
       Pervasives.compare .  Along with	the type t , this function compare al-
       lows  the  module  String  to  be  passed  as  argument to the functors
       Set.Make	and Map.Make .

       val equal : t ->	t -> bool

       The equal function for strings.

       Since 4.03.0

       val split_on_char : char	-> string -> string list

       String.split_on_char sep	s returns the list  of	all  (possibly	empty)
       substrings of s that are	delimited by the sep character.

       The function's output is	specified by the following invariants:

       -The list is not	empty.

       -Concatenating  its  elements using sep as a separator returns a	string
       equal   to   the	  input	  (   String.concat   (String.make   1	  sep)
       (String.split_on_char sep s) = s	).

       -No string in the result	contains the sep character.

       Since 4.04.0

2020-08-11			    source:			     String(3)

NAME | Module | Documentation

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=String&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help