<commit_before>! Copyright (C) 2008 <NAME>.
! See http://factorcode.org/license.txt for BSD license.
USING: assocs help.markup help.syntax math sequences kernel ;
IN: math.bitwise

HELP: bitfield
{ $values { "values..." "a series of objects on the stack" } { "bitspec" "an array" } { "n" integer } }
{ $description "Constructs an integer (bit field) from a series of values on the stack together with a bit field specifier, which is an array whose elements have one of the following shapes:"
{ $list
    { { $snippet "{ word shift }" } " - " { $snippet "word" } " is applied to the top of the stack and the result is shifted to the left by " { $snippet "shift" } " bits and bitor'd with the bit field" }
    { { $snippet "shift" } " - the top of the stack is shifted to the left by " { $snippet "shift" } " bits and bitor'd with the bit field" }
    { { $snippet "{ constant shift }" } " - " { $snippet "constant" } " is shifted to the left by " { $snippet "shift" } " bits and bitor'd with the bit field" }
}
"The bit field specifier is processed left to right, so stack values should be supplied in reverse order." }
{ $examples
    "Consider the following specification:"
    { $list
        { "bits 0-10 are set to the value of " { $snippet "x" } }
        { "bits 11-14 are set to the value of " { $snippet "y" } }
        { "bit 15 is always on" }
        { "bits 16-20 are set to the value of " { $snippet "fooify" } " applied to " { $snippet "z" } }
    }
    "Such a bit field construction can be specified with a word like the following:"
    { $example
        "USING: math math.bitwise prettyprint ;"
        "IN: math.bitwise.examples"
        ": fooify ( x -- y ) 0b1111 bitand ;"
        ": baz-bitfield ( x y z -- n )"
        "    {"
        "        { fooify 16 }"
        "        { 1 15 }"
        "        11"
        "        0"
        "    } bitfield ;"
        "3 2 1 baz-bitfield ."
        "102403"
    }
    "Square the 3 from the stack and shift 8, place the 1 from the stack at bit 5, and shift a constant 1 to bit 2:"
    { $example
        "USING: math math.bitwise prettyprint ;"
        "1 3"
        "    {"
        "        { sq 8 }"
        "        5"
        "        { 1 2 }"
        "    } bitfield .b"
        "0b100100100100"
    }
} ;

HELP: bitfield*
{ $values { "values..." "a series of objects on the stack" } { "bitspec" "an array" } { "n" integer } }
{ $description "Constructs an integer (bit field) from a series of values on the stack together with a bit field specifier, which is an array whose elements have one of the following shapes:"
{ $list
    { { $snippet "{ word shift }" } " - " { $snippet "word" } " is applied to the top of the stack and the result is shifted to the left by " { $snippet "shift" } " bits and bitor'd with the bit field" }
    { { $snippet "shift" } " - the top of the stack is shifted to the left by " { $snippet "shift" } " bits and bitor'd with the bit field" }
    { { $snippet "{ constant shift }" } " - " { $snippet "constant" } " is shifted to the left by " { $snippet "shift" } " bits and bitor'd with the bit field" }
}
"The bit field specifier is processed left to right, so stack values should be supplied in reverse order." }
{ $examples
    "Consider the following specification:"
    { $list
        { "bits 0-10 are set to the value of " { $snippet "x" } }
        { "bits 11-14 are set to the value of " { $snippet "y" } }
        { "bit 15 is always on" }
        { "bits 16-20 are set to the value of " { $snippet "fooify" } " applied to " { $snippet "z" } }
    }
    "Such a bit field construction can be specified with a word like the following:"
    { $example
        "USING: math math.bitwise prettyprint ;"
        "IN: math.bitwise.examples"
        ": fooify ( x -- y ) 0b1111 bitand ;"
        ": baz-bitfield* ( x y z -- n )"
        "    {"
        "        0"
        "        11"
        "        { 1 15 }"
        "        { fooify 16 }"
        "    } bitfield* ;"
        "1 2 3 baz-bitfield* ."
        "233473"
    }
    "Square the 3 from the stack and shift 8, place the 1 from the stack at bit 5, and shift a constant 1 to bit 2:"
    { $example
        "USING: math math.bitwise prettyprint ;"
        "1 3"
        "    {"
        "        { sq 8 }"
        "        5"
        "        { 1 2 }"
        "    } bitfield .b"
        "0b100100100100"
    }
} ;

HELP: bits
{ $values { "m" integer } { "n" integer } { "m'" integer } }
{ $description "Keep only " { $snippet "n" } " bits from the integer " { $snippet "m" } ". For negative numbers, represent the number as two's complement (a positive integer representing a negative integer)." }
{ $examples
    { $example
        "USING: math.bitwise prettyprint ;"
        "0x123abcdef 16 bits .h"
        "0xcdef"
    }
    { $example
        "USING: math.bitwise prettyprint ;"
        "-2 16 bits .h"
        "0xfffe"
    }
} ;<commit_msg>math.bitwise: Fix example for bitfield*<commit_after>! Copyright (C) 2008 <NAME>.
! See http://factorcode.org/license.txt for BSD license.
USING: assocs help.markup help.syntax math sequences kernel ;
IN: math.bitwise

HELP: bitfield
{ $values { "values..." "a series of objects on the stack" } { "bitspec" "an array" } { "n" integer } }
    { $description "Constructs an integer (bit field) from a series of values on the stack together with a bit field specifier, which is an array whose elements have one of the following shapes:"
    { $list
        { { $snippet "{ word shift }" } " - " { $snippet "word" } " is applied to the top of the stack and the result is shifted to the left by " { $snippet "shift" } " bits and bitor'd with the bit field" }
        { { $snippet "shift" } " - the top of the stack is shifted to the left by " { $snippet "shift" } " bits and bitor'd with the bit field" }
        { { $snippet "{ constant shift }" } " - " { $snippet "constant" } " is shifted to the left by " { $snippet "shift" } " bits and bitor'd with the bit field" }
    }
    "The last entry in the bit field specifier is processed in reverse, so stack values are supplied in reverse order, e.g. the leftmost stack value is the last bit field specifier."
}
{ $examples
    "Consider the following specification:"
    { $list
        { "bits 0-10 are set to the value of " { $snippet "x" } }
        { "bits 11-14 are set to the value of " { $snippet "y" } }
        { "bit 15 is always on" }
        { "bits 16-20 are set to the value of " { $snippet "fooify" } " applied to " { $snippet "z" } }
    }
    "Such a bit field construction can be specified with a word like the following:"
    { $example
        "USING: math math.bitwise prettyprint ;"
        "IN: math.bitwise.examples"
        ": fooify ( x -- y ) 0b1111 bitand ;"
        ": baz-bitfield ( x y z -- n )"
        "    {"
        "        { fooify 16 }"
        "        { 1 15 }"
        "        11"
        "        0"
        "    } bitfield ;"
        "3 2 1 baz-bitfield ."
        "102403"
    }
    "Square the 3 from the stack and shift 8, place the 1 from the stack at bit 5, and shift a constant 1 to bit 2:"
    { $example
        "USING: math math.bitwise prettyprint ;"
        "1 3"
        "    {"
        "        { sq 8 }"
        "        5"
        "        { 1 2 }"
        "    } bitfield .b"
        "0b100100100100"
    }
} ;

HELP: bitfield*
{ $values { "values..." "a series of objects on the stack" } { "bitspec" "an array" } { "n" integer } }
{ $description "Constructs an integer (bit field) from a series of values on the stack together with a bit field specifier, which is an array whose elements have one of the following shapes:"
    { $list
        { { $snippet "{ word shift }" } " - " { $snippet "word" } " is applied to the top of the stack and the result is shifted to the left by " { $snippet "shift" } " bits and bitor'd with the bit field" }
        { { $snippet "shift" } " - the top of the stack is shifted to the left by " { $snippet "shift" } " bits and bitor'd with the bit field" }
        { { $snippet "{ constant shift }" } " - " { $snippet "constant" } " is shifted to the left by " { $snippet "shift" } " bits and bitor'd with the bit field" }
    }
    "The bit field specifier is processed in order, so stack values are taken from left to right."
}
{ $examples
    "Consider the following specification:"
    { $list
        { "bits 0-10 are set to the value of " { $snippet "x" } }
        { "bits 11-14 are set to the value of " { $snippet "y" } }
        { "bit 15 is always on" }
        { "bits 16-20 are set to the value of " { $snippet "fooify" } " applied to " { $snippet "z" } }
    }
    "Such a bit field construction can be specified with a word like the following:"
    { $example
        "USING: math math.bitwise prettyprint ;"
        "IN: math.bitwise.examples"
        ": fooify ( x -- y ) 0b1111 bitand ;"
        ": baz-bitfield* ( x y z -- n )"
        "    {"
        "        0"
        "        11"
        "        { 1 15 }"
        "        { fooify 16 }"
        "    } bitfield* ;"
        "1 2 3 baz-bitfield* ."
        "233473"
    }
    "Put a 1 at bit 1, put the 1 from the stack at bit 5, square the 3 and put it at bit 8:"
    { $example
        "USING: math math.bitwise prettyprint ;"
        "1 3"
        "    {"
        "        { 1 2 }"
        "        5"
        "        { sq 8 }"
        "    } bitfield* .b"
        "0b100100100100"
    }
} ;

{ bitfield bitfield* } related-words

HELP: bits
{ $values { "m" integer } { "n" integer } { "m'" integer } }
{ $description "Keep only " { $snippet "n" } " bits from the integer " { $snippet "m" } ". For negative numbers, represent the number as two's complement (a positive integer representing a negative integer)." }
{ $examples
    { $example
        "USING: math.bitwise prettyprint ;"
        "0x123abcdef 16 bits .h"
        "0xcdef"
    }
    { $example
        "USING: math.bitwise prettyprint ;"
        "-2 16 bits .h"
        "0xfffe"
    }
} ;
{'fraction_non_alphanumeric': 0.12253281234345256, 'fraction_numerical': 0.027051397655545536, 'mean_word_length': 2.0276008492569004, 'pattern_counts': {'":': 8, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4137158', 'n_tokens_mistral': 3354, 'n_tokens_neox': 3117, 'n_words': 1241}